Merge pull request #93889 from gaurav-nelson/ROX-29281-keyless-quay

[RHACS] Add Quay keyless authentication procedure

Author: gaurav-nelson

cli/image-scanning-by-using-the-roxctl-cli.adoc

@@ -16,7 +16,7 @@ By specifying the appropriate cluster in the delegated scanning configuration or
 
 [IMPORTANT]
 ====
-For more information about how to configure delegated image scanning, see xref:../operating/examine-images-for-vulnerabilities.adoc#configuring-delegated-image-scanning_examine-images-for-vulnerabilities[Configuring delegated image scanning].
+For more information about how to configure delegated image scanning, see xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning].
 ====
 
 .Procedure

integration/integrate-with-image-registries.adoc

@@ -73,6 +73,14 @@ include::modules/manual-configuration-image-registry-qcr.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 * xref:../integration/integrate-with-image-vulnerability-scanners.adoc#integrate-with-qcr-scanner_integrate-with-image-vulnerability-scanners[Integrating with Quay Container Registry to scan images]
+* link:https://external-secrets.io/latest/api/generator/quay/[External Secrets Operator - Quay]
+
+include::modules/quay-keyless-eso.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning].
 
 include::modules/manual-configuration-image-registry-ghcr.adoc[leveloffset=+2]
 

modules/manual-configuration-image-registry-qcr.adoc

@@ -7,9 +7,13 @@
 
 You can integrate {product-title} ({product-title-short}) with Quay Container Registry. You can integrate with Quay by using the following methods:
 
-- Integrating with the Quay public repository (registry): This method does not require authentication.
-- Integrating with a Quay private registry by using a robot account: This method requires that you create a robot account to use with Quay (recommended). See the link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/use_red_hat_quay/use-quay-manage-repo#allow-robot-access-user-repo[Quay documentation] for more information.
-- Integrating with Quay to use the Quay scanner rather than the {product-title-short} scanner:  This method uses the API and requires an OAuth token for authentication. See "Integrating with Quay Container Registry to scan images" in the "Additional Resources" section.
+* Integrating with the Quay public repository (registry): This method does not require authentication.
+* Integrating with a Quay private registry:
+
+** By using a robot account: This method requires that you create a robot account to use with Quay (recommended). See the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.14/html/about_quay_io/allow-robot-access-user-repo[Red{nbsp}Hat Quay Robot Account overview] topic in Quay documentation for more information.
+** By using keyless authentication with external secret: This method uses OIDC federation and the External Secrets Operator (ESO). For more information, see "Enabling Quay registry keyless authentication using external secret".
+
+* Integrating with Quay to use the Quay scanner rather than the {product-title-short} scanner: This method uses the API and requires an OAuth token for authentication. For more information, see "Integrating with Quay Container Registry to scan images" in the "Additional resources" section.
 
 .Prerequisites
 * For authentication with a Quay private registry, you need the credentials associated with a robot account or an OAuth token (deprecated).
@@ -20,16 +24,16 @@ You can integrate {product-title} ({product-title-short}) with Quay Container Re
 . Click *New integration*.
 . Enter the *Integration name.*
 . Enter the *Endpoint*, or the address of the registry.
-.. If you are integrating with the Quay public repository, under *Type*, select *Registry*, and then go to the next step. 
+.. If you are integrating with the Quay public repository, under *Type*, select *Registry*, and then go to the next step.
 .. If you are integrating with a Quay private registry, under *Type*, select *Registry* and enter information in the following fields:
 ** *Robot username*: If you are accessing the registry by using a Quay robot account, enter the user name in the format `_<namespace>+<accountname>_`.
 ** *Robot password*: If you are accessing the registry by using a Quay robot account, enter the password for the robot account user name.
-** *OAuth token*: If you are accessing the registry by using an OAuth token (deprecated), enter it in this field. 
+** *OAuth token*: If you are accessing the registry by using an OAuth token (deprecated), enter it in this field.
 . Optional: If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*.
 . Optional: To create the integration without testing, select *Create integration without testing*.
 . Select *Save*.
 
 [NOTE]
 ====
-If you are editing a Quay integration but do not want to update your credentials, verify that *Update stored credentials* is not selected. 
+If you are editing a Quay integration but do not want to update your credentials, verify that *Update stored credentials* is not selected.
 ====

modules/quay-keyless-eso.adoc

@@ -0,0 +1,113 @@
+// Module included in the following assemblies:
+//
+// * integration/integrate-with-image-registries.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="quay-keyless-eso_{context}"]
+= Enabling Quay registry keyless authentication using external secret
+
+For validating images stored in Quay private registries, you can configure {product-title-short} to use keyless authentication with Red{nbsp}Hat Quay registries. This method uses the External Secrets Operator (ESO) and OpenID Connect (OIDC) federation.
+
+.Prerequisites
+
+* You have enabled delegated scanning in {product-title-short}. For more information, see "Accessing delegated image scanning" in the "Additional resources" section.
+* The Central endpoint configured for the Secured Cluster `centralEndpoint: central.stackrox:443` or similar.
+* A robot account created in Red{nbsp}Hat Quay with OIDC federation configured.
++
+--
+* The issuer URL in the Quay robot identity federation configuration must match the service account token issuer of your {ocp} cluster.
+* The `sub claim` subject must match the service account name and namespace that you configure in your cluster.
+--
++
+See the link:https://docs.redhat.com/en/documentation/red_hat_quay/latest/html/about_quay_io/allow-robot-access-user-repo[Red Hat Quay Robot Account overview] topic in Quay documentation for more information.
+
+.Procedure
+
+. In your Quay instance, navigate to your robot account settings and configure OIDC federation.
++
+Ensure the *Issuer URL* and *Subject* fields are correctly set to match your {ocp} service account that ESO uses. See the link:https://docs.redhat.com/en/documentation/red_hat_quay/latest/html/about_quay_io/allow-robot-access-user-repo#setting-robot-federation[Setting up robot account federation] topic in the Red Hat Quay documentation for more information.
+
+. If ESO is not already present in your cluster, install it using Helm or another preferred method.
++
+[source,terminal,subs="+attributes"]
+----
+$ helm repo add external-secrets https://charts.external-secrets.io
+helm install external-secrets \
+  external-secrets/external-secrets \
+  -n external-secrets \
+  --create-namespace
+----
+
+. Define and apply the following Kubernetes resources. This example creates a `ServiceAccount` resource, a `QuayAccessToken` generator resource provided by the ESO installation, and an `ExternalSecret` resource that uses the generator to create a `kubernetes.io/dockerconfigjson` secret in the specified namespace.
++
+[IMPORTANT]
+====
+Update the `robotAccount` field in the `QuayAccessToken` resource to match the name of your Quay robot account.
+====
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: quay
+  namespace: quay
+---
+apiVersion: generators.external-secrets.io/v1alpha1
+kind: QuayAccessToken
+metadata:
+  name: quay-token
+  namespace: quay
+spec:
+  url: quay.io
+  robotAccount: keyless+account # <1>
+  serviceAccountRef:
+    name: quay
+    namespace: quay
+---
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: quay-credentials
+  namespace: quay
+spec:
+  dataFrom:
+  - sourceRef:
+      generatorRef:
+        apiVersion: generators.external-secrets.io/v1alpha1
+        kind: QuayAccessToken
+        name: quay-token
+  refreshInterval: 55m
+  target:
+    name: quay-credentials
+    template:
+      type: kubernetes.io/dockerconfigjson
+      data:
+        .dockerconfigjson: |
+          {
+            "auths": {
+              "{{ .registry }}": {
+                "auth": "{{ .auth }}"
+              }
+            }
+          }
+----
+<1> Replace `keyless+account` with the actual name of your Quay robot account.
+
+.Verification
+
+* Confirm that ESO has successfully created a secret named `quay-credentials` of type `kubernetes.io/dockerconfigjson` in the specified namespace.
++
+[source,terminal]
+----
+$ kubectl get secret quay-credentials -n quay -o yaml
+----
+
+The keyless authentication method supports image scanning by using **delegated scanning**.
+
+* Use delegated image scanning by running the following command:
++
+[source,terminal]
+----
+$ roxctl image scan <image_name> --namespace=<namespace_where_secret_exists> <1>
+----
+<1> Specify the image name and namespace where you created the secret.