OSDOCS-16959-config-req-header CQA

authentication/identity_providers/configuring-request-header-identity-provider.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Configure the `request-header` identity provider to identify users from request header values, such as `X-Remote-User`. It is typically used in combination with an authenticating proxy, which sets the request header value.
+[role="_abstract"]
+Configure the `request-header` identity provider to identify users from request header values, such as `X-Remote-User`. Use this provider when an authenticating proxy validates users and sets those headers for {product-title}.
 
 include::modules/identity-provider-overview.adoc[leveloffset=+1]
 
@@ -20,18 +21,12 @@ include::modules/identity-provider-request-header-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]
 
-[id="example-apache-auth-config-using-request-header"]
-== Example Apache authentication configuration using request header
+include::modules/identity-provider-apache-custom-proxy-configuration.adoc[leveloffset=+1]
 
-This example configures an Apache authentication proxy for the {product-title}
-using the request header identity provider.
+include::modules/identity-provider-configuring-apache-request-header.adoc[leveloffset=+1]
 
 
-include::modules/identity-provider-apache-custom-proxy-configuration.adoc[leveloffset=+2]
-
-
-include::modules/identity-provider-configuring-apache-request-header.adoc[leveloffset=+2]

modules/identity-provider-about-request-header.adoc

@@ -6,39 +6,28 @@
 [id="identity-provider-about-request-header_{context}"]
 = About request header authentication
 
-A request header identity provider identifies users from request
-header values, such as `X-Remote-User`. It is typically used in combination with
-an authenticating proxy, which sets the request header value. The
-request header identity provider cannot be combined with other identity providers
-that use direct password logins, such as htpasswd, Keystone, LDAP or basic authentication.
+[role="_abstract"]
+Configure request header authentication to identify users from header values such as `X-Remote-User`. Use an authenticating proxy with mutual TLS (mTLS) so the proxy validates users and sets the identity header for {product-title}.
+
+The request header identity provider is typically used in combination with an authenticating proxy, which sets the request header value. This identity provider cannot be combined with other identity providers that use direct password logins, such as htpasswd, Keystone, LDAP or basic authentication.
 
 [NOTE]
 ====
-You can also use the request header identity provider for advanced configurations
-such as the community-supported link:https://github.com/openshift/request-header-saml-service-provider[SAML authentication].
-Note that this solution is not supported by Red Hat.
+You can also use the request header identity provider for advanced configurations such as the community-supported SAML application. This solution is not supported by Red Hat.
 ====
 
-For users to authenticate using this identity provider, they must access
-`https://_<namespace_route>_/oauth/authorize` (and subpaths) via an authenticating proxy.
-To accomplish this, configure the OAuth server to redirect unauthenticated
-requests for OAuth tokens to the proxy endpoint that proxies to
-`https://_<namespace_route>_/oauth/authorize`.
+For users to authenticate using this identity provider, they must access `https://_<namespace_route>_/oauth/authorize` and subpaths of that endpoint via an authenticating proxy. To accomplish this, configure the OAuth server to redirect unauthenticated
+requests for OAuth tokens to the proxy endpoint that proxies to `https://_<namespace_route>_/oauth/authorize`.
 
 To redirect unauthenticated requests from clients expecting browser-based login flows:
 
-* Set the `provider.loginURL` parameter to the authenticating proxy URL that
-will authenticate interactive clients and then proxy the request to
-`https://_<namespace_route>_/oauth/authorize`.
+* Set the `provider.loginURL` parameter to the authenticating proxy URL that authenticates interactive clients and then proxy the request to `https://_<namespace_route>_/oauth/authorize`.
 
 To redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges:
 
-* Set the `provider.challengeURL` parameter to the authenticating proxy URL that
-will authenticate clients expecting `WWW-Authenticate` challenges and then proxy
-the request to `https://_<namespace_route>_/oauth/authorize`.
+* Set the `provider.challengeURL` parameter to the authenticating proxy URL that authenticates clients expecting `WWW-Authenticate` challenges and then proxy the request to `https://_<namespace_route>_/oauth/authorize`.
 
-The `provider.challengeURL` and `provider.loginURL` parameters can include
-the following tokens in the query portion of the URL:
+The `provider.challengeURL` and `provider.loginURL` parameters can include the following tokens in the query portion of the URL:
 
 * `${url}` is replaced with the current URL, escaped to be safe in a query parameter.
 +
@@ -50,21 +39,18 @@ For example: [x-]`https://www.example.com/auth-proxy/oauth/authorize?${query}`
 
 [IMPORTANT]
 ====
-As of {product-title} 4.1, your proxy must support mutual TLS.
+As of {product-title} 4.1, your proxy must support mTLS.
 ====
 
 [id="sspi-windows_{context}"]
-== SSPI connection support on Microsoft Windows
+== Security Support Provider Interface connection support on Microsoft Windows
 
 ifdef::openshift-enterprise,openshift-webscale[]
 
-:FeatureName: Using SSPI connection support on Microsoft Windows
+:FeatureName: Using Security Support Provider Interface connection support on Microsoft Windows
 include::snippets/technology-preview.adoc[leveloffset=+1]
 
 endif::[]
 
-The OpenShift CLI (`oc`) supports the Security Support Provider Interface (SSPI) to allow for SSO
-flows on Microsft Windows. If you use the request header identity provider with a
-GSSAPI-enabled proxy to connect an Active Directory server to {product-title},
-users can automatically authenticate to {product-title} by using the `oc`  command
-line interface from a domain-joined Microsoft Windows computer.
+The Security Support Provider Interface (SSPI) enables the OpenShift CLI (`oc`) to support SSO
+flows on Microsoft Windows. If you use the request header identity provider with a GSSAPI-enabled proxy to connect an Active Directory server to {product-title}, users can automatically authenticate to {product-title} by using the `oc` command line interface from a domain-joined Microsoft Windows computer.

modules/identity-provider-add.adoc

@@ -29,13 +29,13 @@ 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 your cluster after you define it. This step enables users to authenticate with the configured identity provider.
 
 .Prerequisites
 
 * Create an {product-title} cluster.
-* Create the custom resource (CR) for your identity providers.
+* Create the CR for your identity providers.
 * You must be logged in as an administrator.
 
 .Procedure
@@ -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, passing in the token to authenticate, by running the following command:
 +
 [source,terminal]
 ----
@@ -80,9 +79,9 @@ $ oc login --token=<token>
 [NOTE]
 ====
 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.
+If your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, you can log in with a username 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 using the following command, which prompts for your username and password:
 
 [source,terminal]
 ----
@@ -91,12 +90,12 @@ $ 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 the username displays by running the following command:
 +
 [source,terminal]
 ----

modules/identity-provider-apache-custom-proxy-configuration.adoc

@@ -3,33 +3,31 @@
 // * authentication/identity_providers/configuring-request-header-identity-provider.adoc
 
 :_mod-docs-content-type: CONCEPT
+[id="example-apache-auth-config-using-request-header_{context}"]
+= Example Apache authentication configuration using request header
+
+[role="_abstract"]
+Review this example to configure an Apache authentication proxy with the request header identity provider. Use it to set up a proxy that validates users and forwards trusted identity headers to {product-title}.
+
+This example configures an Apache authentication proxy for {product-title} using the request header identity provider.
+
+== Custom proxy configuration
 [id="identity-provider-apache-custom-proxy-configuration_{context}"]
-= Custom proxy configuration
 
-Using the `mod_auth_gssapi` module is a popular way to configure the Apache
-authentication proxy using the request header identity provider; however, it is
-not required. Other proxies can easily be used if the following requirements are
+Review the requirements for a custom authentication proxy used with the request header identity provider. Meeting these requirements prevents header spoofing and ensures OAuth authorization flows work correctly.
+
+Using the `mod_auth_gssapi` module is a popular way to configure the Apache authentication proxy using the request header identity provider. However, it is not required. Other proxies can easily be used if the following requirements are
 met:
 
-* Block the `X-Remote-User` header from client requests to prevent spoofing.
-* Enforce client certificate authentication in the `RequestHeaderIdentityProvider`
-configuration.
-* Require the `X-Csrf-Token` header be set for all authentication requests using
-the challenge flow.
-* Make sure only the `/oauth/authorize` endpoint and its subpaths are proxied;
-redirects must be rewritten to allow the backend server to send the client to
-the correct location.
-* The URL that proxies to `\https://<namespace_route>/oauth/authorize` must end
-with `/authorize` with no trailing slash. For example, `\https://proxy.example.com/login-proxy/authorize?...`
-must proxy to `\https://<namespace_route>/oauth/authorize?...`.
-+
-* Subpaths of the URL that proxies to `\https://<namespace_route>/oauth/authorize`
-must proxy to subpaths of `\https://<namespace_route>/oauth/authorize`. For
-example, `\https://proxy.example.com/login-proxy/authorize/approve?...` must
+* Blocks the `X-Remote-User` header from client requests to prevent spoofing.
+* Enforces client certificate authentication in the `RequestHeaderIdentityProvider` configuration.
+* Requires the `X-Csrf-Token` header be set for all authentication requests using the challenge flow.
+* Ensures only the `/oauth/authorize` endpoint and subpaths of that endpoint are proxied. Redirects must be rewritten to allow the backend server to send the client to the correct location.
+* The URL that proxies to `\https://<namespace_route>/oauth/authorize` must end with `/authorize` with no trailing slash. For example, `\https://proxy.example.com/login-proxy/authorize?...` must proxy to `\https://<namespace_route>/oauth/authorize?...`.
+* Subpaths of the URL that proxies to `\https://<namespace_route>/oauth/authorize` must proxy to subpaths of `\https://<namespace_route>/oauth/authorize`. For example, `\https://proxy.example.com/login-proxy/authorize/approve?...` must
 proxy to `\https://<namespace_route>/oauth/authorize/approve?...`.
 
 [NOTE]
 ====
-The `\https://<namespace_route>` address is the route to the OAuth server and
-can be obtained by running `oc get route -n openshift-authentication`.
+The `\https://<namespace_route>` address is the route to the OAuth server and can be obtained by running `oc get route -n openshift-authentication`.
 ====

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 that contains the certificate authority bundle for the identity provider. {product-title} uses this bundle to validate transport layer security (TLS) connections when configuring the provider.
 
 ifdef::github[]
 [NOTE]
@@ -28,19 +27,15 @@ 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:
 +
 [source,terminal]
 ----
 $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
 ----
 +
-[TIP]
-====
-You can alternatively apply the following YAML to create the config map:
-
+** Alternatively, apply the following YAML to create the config map:
++
 [source,yaml]
 ----
 apiVersion: v1
@@ -52,7 +47,8 @@ data:
   ca.crt: |
     <CA_certificate_PEM>
 ----
-====
++
+The certificate authority must be stored in the `ca.crt` key of the `ConfigMap` object.
 
 // Undefining attributes
 ifeval::["{context}" == "configuring-google-identity-provider"]