From 942e94a7755f2d5d7c0c5a4f21c65ad77ccdb8e0 Mon Sep 17 00:00:00 2001 From: William Gabor Date: Thu, 23 Jul 2026 16:48:54 -0400 Subject: [PATCH] OSDOCS-16959-config-oidc-provider CQA --- .../configuring-oidc-identity-provider.adoc | 10 ++- modules/identity-provider-add.adoc | 19 +++--- modules/identity-provider-config-map.adoc | 11 ++-- ...rovider-configuring-using-web-console.adoc | 6 +- modules/identity-provider-oidc-CR.adoc | 62 +++++++++++-------- modules/identity-provider-oidc-about.adoc | 3 + modules/identity-provider-oidc-supported.adoc | 21 ++++--- modules/identity-provider-secret.adoc | 9 +-- 8 files changed, 80 insertions(+), 61 deletions(-) diff --git a/authentication/identity_providers/configuring-oidc-identity-provider.adoc b/authentication/identity_providers/configuring-oidc-identity-provider.adoc index eda44c3fc22b..367b8fc1eca4 100644 --- a/authentication/identity_providers/configuring-oidc-identity-provider.adoc +++ b/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::[] diff --git a/modules/identity-provider-add.adoc b/modules/identity-provider-add.adoc index d6a460a966cc..e93a8cafbf33 100644 --- a/modules/identity-provider-add.adoc +++ b/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,8 +81,8 @@ $ oc login --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 --server= @@ -91,12 +90,12 @@ $ oc login -u --server= 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] ---- diff --git a/modules/identity-provider-config-map.adoc b/modules/identity-provider-config-map.adoc index e403dd031eac..de1375372231 100644 --- a/modules/identity-provider-config-map.adoc +++ b/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] ---- diff --git a/modules/identity-provider-configuring-using-web-console.adoc b/modules/identity-provider-configuring-using-web-console.adoc index 52282366502c..f5743fb29e24 100644 --- a/modules/identity-provider-configuring-using-web-console.adoc +++ b/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. ==== diff --git a/modules/identity-provider-oidc-CR.adoc b/modules/identity-provider-oidc-CR.adoc index eda1a83620a6..54ba97d4d085 100644 --- a/modules/identity-provider-oidc-CR.adoc +++ b/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../oauth2callback/`. -<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../oauth2callback/`. +`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. + diff --git a/modules/identity-provider-oidc-about.adoc b/modules/identity-provider-oidc-about.adoc index d7ef43cc1d57..9f30ac365c54 100644 --- a/modules/identity-provider-oidc-about.adoc +++ b/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[] diff --git a/modules/identity-provider-oidc-supported.adoc b/modules/identity-provider-oidc-supported.adoc index 88d04abcc3d9..78fdf8a035d6 100644 --- a/modules/identity-provider-oidc-supported.adoc +++ b/modules/identity-provider-oidc-supported.adoc @@ -6,7 +6,10 @@ [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 + @@ -14,15 +17,17 @@ Red Hat tests and supports specific OpenID Connect (OIDC) providers with {produc ==== 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 diff --git a/modules/identity-provider-secret.adoc b/modules/identity-provider-secret.adoc index edf9175055d9..0a0bae22fbe4 100644 --- a/modules/identity-provider-secret.adoc +++ b/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 --from-literal=clientSecret= -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] ----