OSDOCS-16959-config-oidc-provider CQA

authentication/identity_providers/configuring-oidc-identity-provider.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Configure the `oidc` identity provider to integrate with an OpenID Connect identity provider using an link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow].
+[role="_abstract"]
+Configure the `oidc` identity provider to integrate {product-title} with an external OpenID Connect (OIDC) identity provider using the Authorization Code Flow. Use this integration when your organization already uses OIDC for single sign-on.
 
 ifdef::openshift-origin,openshift-enterprise,openshift-webscale[]
 include::modules/identity-provider-overview.adoc[leveloffset=+1]
@@ -31,10 +32,15 @@ include::modules/identity-provider-oidc-CR.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers.
+* xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters]
 
 include::modules/identity-provider-add.adoc[leveloffset=+1]
 
 include::modules/identity-provider-configuring-using-web-console.adoc[leveloffset=+1]
 
+[id="additional-resources-configuring-oidc-identity-provider"]
+== Additional resources
+
+* link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]
+
 endif::[]

modules/identity-provider-add.adoc

@@ -29,8 +29,8 @@ endif::[]
 [id="add-identity-provider_{context}"]
 = Adding an identity provider to your cluster
 
-After you install your cluster, add an identity provider to it so your
-users can authenticate.
+[role="_abstract"]
+Apply the identity provider custom resource (CR) to add the provider to your cluster. After the provider is configured, users can authenticate to {product-title} with credentials from the remote identity provider.
 
 .Prerequisites
 
@@ -40,7 +40,7 @@ users can authenticate.
 
 .Procedure
 
-. Apply the defined CR:
+. Apply the defined CR by running the following command:
 +
 [source,terminal]
 ----
@@ -53,8 +53,7 @@ If a CR does not exist, `oc apply` creates a new CR and might trigger the follow
 ====
 
 ifndef::no-username-password-login[]
-. Log in to the cluster as a user from your identity provider, entering the
-password when prompted.
+. Log in to the cluster as a user from your identity provider by running the following command. Enter the password when prompted.
 +
 [source,terminal]
 ----
@@ -70,7 +69,7 @@ As long as the `kubeadmin` user has been removed, the `oc login` command provide
 +
 You can also access this page from the web console by navigating to *(?) Help* -> *Command Line Tools* -> *Copy Login Command*.
 
-. Log in to the cluster, passing in the token to authenticate.
+. Log in to the cluster by runningn the following command. Pass in the token to authenticate.
 +
 [source,terminal]
 ----
@@ -82,21 +81,21 @@ $ oc login --token=<token>
 ifdef::oidc[]
 If your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, you can log in with a user name and password. You might need to take steps to enable the ROPC grant flow for your identity provider.
 
-After the OIDC identity provider is configured in {product-title}, you can log in by using the following command, which prompts for your user name and password:
-
+. After the OIDC identity provider is configured in {product-title}, you can log in by running the following command, which prompts for your user name and password:
++
 [source,terminal]
 ----
 $ oc login -u <identity_provider_username> --server=<api_server_url_and_port>
 ----
 endif::oidc[]
 
 ifndef::oidc[]
-This identity provider does not support logging in with a user name and password.
+This identity provider does not support logging in with a username and password.
 endif::oidc[]
 ====
 endif::no-username-password-login[]
 
-. Confirm that the user logged in successfully, and display the user name.
+. Confirm that the user logged in successfully and that the username displays by running the following command:
 +
 [source,terminal]
 ----

modules/identity-provider-config-map.adoc

@@ -15,9 +15,8 @@ endif::[]
 [id="identity-provider-creating-configmap_{context}"]
 = Creating a config map
 
-Identity providers use {product-title} `ConfigMap` objects in the `openshift-config`
-namespace to contain the certificate authority bundle. These are primarily
-used to contain certificate bundles needed by the identity provider.
+[role="_abstract"]
+Create a `ConfigMap` object in the `openshift-config` namespace to store the certificate authority bundle for your identity provider. The identity provider custom resource (CR) references this config map during configuration.
 
 ifdef::github[]
 [NOTE]
@@ -28,9 +27,7 @@ endif::github[]
 
 .Procedure
 
-* Define an {product-title} `ConfigMap` object containing the
-certificate authority by using the following command. The certificate
-authority must be stored in the `ca.crt` key of the `ConfigMap` object.
+* Define an {product-title} `ConfigMap` object containing the certificate authority by running the following command. The certificate authority must be stored in the `ca.crt` key of the `ConfigMap` object.
 +
 [source,terminal]
 ----
@@ -39,7 +36,7 @@ $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-
 +
 [TIP]
 ====
-You can alternatively apply the following YAML to create the config map:
+You can also apply the following YAML to create the config map:
 
 [source,yaml]
 ----

modules/identity-provider-configuring-using-web-console.adoc

@@ -7,7 +7,8 @@
 [id="identity-provider-configuring-using-the-web-console_{context}"]
 = Configuring identity providers using the web console
 
-Configure your identity provider (IDP) through the web console instead of the CLI.
+[role="_abstract"]
+Configure an identity provider through the {product-title} web console as an alternative to applying a custom resource (CR) with the CLI. Use this procedure when you prefer to configure identity providers from the web console.
 
 .Prerequisites
 
@@ -22,6 +23,5 @@ Configure your identity provider (IDP) through the web console instead of the CL
 
 [NOTE]
 ====
-You can specify multiple IDPs through the web console without overwriting
-existing IDPs.
+You can specify multiple IDPs through the web console without overwriting existing IDPs.
 ====

modules/identity-provider-oidc-CR.adoc

@@ -6,7 +6,8 @@
 [id="identity-provider-oidc-CR_{context}"]
 = Sample OpenID Connect CRs
 
-The following custom resources (CRs) show the parameters and acceptable values for an OpenID Connect identity provider.
+[role="_abstract"]
+Review the sample OpenID Connect custom resources (CRs) before you configure the `oidc` identity provider. These examples show required parameters, acceptable values, and optional fields such as custom certificate bundles and extra scopes.
 
 If you must specify a custom certificate bundle, extra scopes, extra authorization request parameters, or a `userInfo` URL, use the full OpenID Connect CR.
 
@@ -19,14 +20,14 @@ metadata:
   name: cluster
 spec:
   identityProviders:
-  - name: oidcidp <1>
-    mappingMethod: claim <2>
+  - name: oidcidp
+    mappingMethod: claim
     type: OpenID
     openID:
-      clientID: ... <3>
-      clientSecret: <4>
+      clientID: ...
+      clientSecret:
         name: idp-secret
-      claims: <5>
+      claims:
         preferredUsername:
         - preferred_username
         name:
@@ -35,14 +36,17 @@ spec:
         - email
         groups:
         - groups
-      issuer: https://www.idp-issuer.com <6>
+      issuer: https://www.idp-issuer.com
 ----
-<1> This provider name is prefixed to the value of the identity claim to form an identity name. It is also used to build the redirect URL.
-<2> Controls how mappings are established between this provider's identities and `User` objects.
-<3> The client ID of a client registered with the OpenID provider. The client must be allowed to redirect to `\https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>`.
-<4> A reference to an {product-title} `Secret` object containing the client secret.
-<5> The list of claims to use as the identity. The first non-empty claim is used.
-<6> The link:https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier[Issuer Identifier] described in the OpenID spec. Must use `https` without query or fragment component.
+
+where:
+
+`spec.identityProviders.name`:: Specifies that this provider name is prefixed to the value of the identity claim to form an identity name. It is also used to build the redirect URL.
+`spec.identityProviders.mappingMethod`:: Controls how mappings are established between this provider's identities and `User` objects.
+`spec.identityProviders.openID.clientID`:: The client ID of a client registered with the OpenID provider. The client must be allowed to redirect to `\https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>`.
+`spec.identityProviders.openID.clientSecret`:: A reference to an {product-title} `Secret` object containing the client secret.
+`spec.identityProviders.openID.claims`:: The list of claims to use as the identity. The first non-empty claim is used.
+`spec.identityProviders.openID.issuer`:: The link:https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier[Issuer Identifier] described in the OpenID spec. Must use `https` without query or fragment component.
 
 .Full OpenID Connect CR
 [source,yaml]
@@ -60,33 +64,37 @@ spec:
       clientID: ...
       clientSecret:
         name: idp-secret
-      ca: <1>
+      ca:
         name: ca-config-map
-      extraScopes: <2>
+      extraScopes:
       - email
       - profile
-      extraAuthorizeParameters: <3>
+      extraAuthorizeParameters:
         include_granted_scopes: "true"
       claims:
-        preferredUsername: <4>
+        preferredUsername:
         - preferred_username
         - email
-        name: <5>
+        name:
         - nickname
         - given_name
         - name
-        email: <6>
+        email:
         - custom_email_claim
         - email
-        groups: <7>
+        groups:
         - groups
       issuer: https://www.idp-issuer.com
 ----
-<1> Optional: Reference to an {product-title} config map containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL.
-<2> Optional: The list of scopes to request, in addition to the `openid` scope, during the authorization token request.
-<3> Optional: A map of extra parameters to add to the authorization token request.
-<4> The list of claims to use as the preferred user name when provisioning a user
+
+where:
+
+`spec.identityProviders.openID.ca`:: Optional: Reference to an {product-title} config map containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL.
+`spec.identityProviders.openID.extraScopes`:: Optional: The list of scopes to request, in addition to the `openid` scope, during the authorization token request.
+`spec.identityProviders.openID.extraauthorizeParameters`:: Optional: A map of extra parameters to add to the authorization token request.
+`spec.identityProviders.openID.claims.preferredUsername`:: The list of claims to use as the preferred user name when provisioning a user
 for this identity. The first non-empty claim is used.
-<5> The list of claims to use as the display name. The first non-empty claim is used.
-<6> The list of claims to use as the email address. The first non-empty claim is used.
-<7> The list of claims to use to synchronize groups from the OpenID Connect provider to {product-title} upon user login. The first non-empty claim is used.
+`spec.identityProviders.openID.claims.name`:: The list of claims to use as the display name. The first non-empty claim is used.
+`spec.identityProviders.openID.claims.email`::  The list of claims to use as the email address. The first non-empty claim is used.
+`spec.identityProviders.openID.claims.groups`::  The list of claims to use to synchronize groups from the OpenID Connect provider to {product-title} upon user login. The first non-empty claim is used.
+

modules/identity-provider-oidc-about.adoc

@@ -6,6 +6,9 @@
 [id="identity-provider-oidc-about_{context}"]
 = About OpenID Connect authentication
 
+[role="_abstract"]
+Review OpenID Connect (OIDC) discovery, scopes, and claim mapping before you configure the `oidc` identity provider. OIDC support and correctly mapped claims are required for the Authentication Operator to authenticate users in {product-title}.
+
 The Authentication Operator in {product-title} requires that the configured OpenID Connect identity provider implements the link:https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect Discovery] specification.
 
 ifdef::openshift-origin[]

modules/identity-provider-oidc-supported.adoc

@@ -6,23 +6,28 @@
 [id="identity-provider-oidc-supported_{context}"]
 = Supported OIDC providers
 
-Red Hat tests and supports specific OpenID Connect (OIDC) providers with {product-title}. The following OpenID Connect (OIDC) providers are tested and supported with {product-title}. Using an OIDC provider that is not on the following list might work with {product-title}, but the provider was not tested by Red Hat and therefore is not supported by Red Hat.
+[role="_abstract"]
+Review the OpenID Connect (OIDC) providers that Red Hat tests and supports with {product-title}. Choose a provider from this list if you need a Red Hat-tested OIDC integration with {product-title}.
+
+The following OpenID Connect (OIDC) providers are tested and supported with {product-title}. Using an OIDC provider that is not on the following list might work with {product-title}, but the provider was not tested by Red Hat and therefore is not supported by Red Hat.
 
 * Active Directory Federation Services for Windows Server
 +
 [NOTE]
 ====
 Currently, it is not supported to use Active Directory Federation Services for Windows Server with {product-title} when custom claims are used.
 ====
-* GitLab
-* Google
-* Keycloak
-* Microsoft Entra ID
+
+** GitLab
+** Google
+** Keycloak
+** Microsoft Entra ID
 +
 [NOTE]
 ====
 Currently, it is not supported to use Microsoft Entra ID when group names are required to be synced.
 ====
-* Okta
-* Ping Identity
-* Red Hat Single Sign-On
+
+** Okta
+** Ping Identity
+** Red Hat Single Sign-On

modules/identity-provider-secret.adoc

@@ -9,11 +9,12 @@
 [id="identity-provider-creating-secret_{context}"]
 = Creating the secret
 
-Identity providers use {product-title} `Secret` objects in the `openshift-config` namespace to contain the client secret, client certificates, and keys.
+[role="_abstract"]
+Create a `Secret` object in the `openshift-config` namespace to store the client secret for your identity provider. The identity provider custom resource (CR) references this secret during configuration.
 
 .Procedure
 
-* Create a `Secret` object containing a string by using the following command:
+. Create a `Secret` object containing a string by running the following command:
 +
 [source,terminal]
 ----
@@ -22,7 +23,7 @@ $ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n
 +
 [TIP]
 ====
-You can alternatively apply the following YAML to create the secret:
+You can also apply the following YAML to create the secret:
 
 [source,yaml]
 ----
@@ -37,7 +38,7 @@ data:
 ----
 ====
 
-* You can define a `Secret` object containing the contents of a file by using the following command:
+. Define a `Secret` object containing the contents of a file by using the following command:
 +
 [source,terminal]
 ----