--- title: Configuring a request header identity provider --- # Configuring a request header identity provider {#configuring-request-header-identity-provider} 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 OpenShift Container Platform. ## Identity providers in OpenShift Container Platform {#identity-provider-overview_configuring-request-header-identity-provider} You can configure identity providers by creating a custom resource (CR) that describes the provider and adding it to the cluster. Identity providers enable user authentication in OpenShift Container Platform beyond the default `kubeadmin` user. > [!NOTE] > OpenShift Container Platform usernames containing `/`, `:`, and `%` are not supported. ## About request header authentication {#identity-provider-about-request-header_configuring-request-header-identity-provider} Request header authentication identifies users from header values such as `X-Remote-User`. An authenticating proxy with mutual TLS (mTLS) validates users and sets the identity header for OpenShift Container Platform. 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 SAML application. This solution is not supported by Red Hat. For users to authenticate using this identity provider, they must access `https://__/oauth/authorize` and subpaths of that endpoint through 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://__/oauth/authorize`. To redirect unauthenticated requests from clients expecting browser-based login flows: - Set the `provider.loginURL` parameter to the authenticating proxy URL that authenticates interactive clients and then proxies the request to `https://__/oauth/authorize`. To redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges: - Set the `provider.challengeURL` parameter to the authenticating proxy URL that authenticates clients expecting `WWW-Authenticate` challenges and then proxy the request to `https://__/oauth/authorize`. 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. For example: `https://www.example.com/sso-login?then=${url}` - `${query}` is replaced with the current query string, unescaped. For example: `https://www.example.com/auth-proxy/oauth/authorize?${query}` > [!IMPORTANT] > As of OpenShift Container Platform 4.1, your proxy must support mTLS. ### Security Support Provider Interface connection support on Microsoft Windows {#sspi-windows_configuring-request-header-identity-provider} > [!IMPORTANT] > Using Security Support Provider Interface connection support on Microsoft Windows is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. > > For more information about the support scope of Red Hat Technology Preview features, see [Technology Preview Features Support Scope](https://access.redhat.com/support/offerings/techpreview/). 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 OpenShift Container Platform, users can automatically authenticate to OpenShift Container Platform by using the `oc` command line interface from a domain-joined Microsoft Windows computer. ## Creating a ConfigMap {#identity-provider-creating-configmap_configuring-request-header-identity-provider} Create a `ConfigMap` object in the `openshift-config` namespace that contains the certificate authority bundle for the identity provider. OpenShift Container Platform uses this bundle to validate Transport Layer Security (TLS) connections to the identity provider. **Procedure** 1. Define an OpenShift Container Platform `ConfigMap` object containing the CA by running the following command: ```terminal $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config ``` 2. Optional: Apply the following YAML to create the config map: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | ``` The CA must be stored in the `ca.crt` key of the `ConfigMap` object. ## Sample request header custom resource {#identity-provider-request-header-CR_configuring-request-header-identity-provider} Review the sample request header `OAuth` custom resource (CR) to understand provider parameters and acceptable values before you configure the identity provider in your cluster. ```yaml apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: requestheaderidp mappingMethod: claim type: RequestHeader requestHeader: challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" ca: name: ca-config-map clientCommonNames: - my-auth-proxy headers: - X-Remote-User - SSO-User emailHeaders: - X-Remote-User-Email nameHeaders: - X-Remote-User-Display-Name preferredUsernameHeaders: - X-Remote-User-Login ``` where: `spec.identityProviders.name` : Specifies that the provider name is prefixed to the username in the request header to form an identity name. `spec.identityProviders.mappingMethod` : Specifies how mappings are established between the identities of this provider and `User` objects. `spec.identityProviders.requestHeader.challengeURL` : Specifies the URL for redirecting unauthenticated `/oauth/authorize` requests to an authenticating proxy that authenticates browser-based clients and then proxies the request to `https://__/oauth/authorize`. The URL that proxies to `https://__/oauth/authorize` must end with `/authorize` with no trailing slash and must also proxy subpaths for OAuth approval flows to work properly. `${url}` is replaced with the current URL, escaped to be safe in a query parameter. `${query}` is replaced with the current query string. If this attribute is not defined, `loginURL` must be used. This value is optional. `spec.identityProviders.requestHeader.loginURL` : Specifies the URL for redirecting unauthenticated `/oauth/authorize` requests to an authenticating proxy that authenticates clients expecting `WWW-Authenticate` challenges and then proxies them to `https://__/oauth/authorize`. `${url}` is replaced with the current URL, escaped to be safe in a query parameter. `${query}` is replaced with the current query string. If this attribute is not defined, `challengeURL` must be used. This value is optional. `spec.identityProviders.requestHeader.ca` : Specifies a reference to an OpenShift Container Platform `ConfigMap` object containing a Privacy-Enhanced Mail (PEM)-encoded certificate bundle used as a trust anchor to validate the Transport Layer Security (TLS) certificates presented by the remote server. > [!IMPORTANT] > As of OpenShift Container Platform 4.1, the `ca` field is required for this identity provider. This means that your proxy must support mutual TLS. `spec.identityProviders.requestHeader.clientCommonNames` : Specifies a list of common names (`cn`). If set, a valid client certificate with a Common Name (`cn`) in the specified list must be presented before the request headers are checked for usernames. If empty, any Common Name is allowed. Can only be used in combination with `ca`. This value is optional. `spec.identityProviders.requestHeader.headers` : Specifies header names to check, in order, for the user identity. The first header containing a value is used as the identity. This field is required, and header matching is case-insensitive. `spec.identityProviders.requestHeader.emailHeaders` : Specifies header names to check, in order, for an email address. The first header containing a value is used as the email address. Header matching is case-insensitive. This value is optional. `spec.identityProviders.requestHeader.nameHeaders` : Specifies header names to check, in order, for a display name. The first header containing a value is used as the display name. Header matching is case-insensitive. This value is optional. `spec.identityProviders.requestHeader.preferredUsernameHeaders` : Specifies header names to check, in order, for a preferred username, if different from the immutable identity determined from the headers specified in `headers`. The first header containing a value is used as the preferred username when provisioning. Header matching is case-insensitive. This value is optional. **Additional resources** {._additional-resources} - [Identity provider parameters](/openshift-docs-markdown/authentication/understanding-identity-provider#identity-provider-parameters_understanding-identity-provider) ## Adding an identity provider to your cluster {#add-identity-provider_configuring-request-header-identity-provider} Apply the identity provider custom resource (CR) to your cluster after you define it. With this configuration, you can authenticate with the configured identity provider. **Prerequisites** - You have access to a OpenShift Container Platform cluster. - You have created the CR for your identity providers. - You are logged in as an administrator. **Procedure** 1. Apply the defined CR by running the following command: ```terminal $ oc apply -f ``` > [!NOTE] > If a CR does not exist, `oc apply` creates a new CR and might trigger the following warning: `Warning: oc apply should be used on resources created by either oc create --save-config or oc apply`. In this case you can safely ignore this warning. 2. Log in to the cluster as a user from your identity provider, entering the password when prompted. ```terminal $ oc login -u ``` 3. Confirm that the user logged in successfully and that the username displays by running the following command: ```terminal $ oc whoami ``` ## Example Apache authentication configuration using request header {#example-apache-auth-config-using-request-header_configuring-request-header-identity-provider} Review this example to configure an Apache authentication proxy with the request header identity provider. Use this example to set up a proxy and connect it to OpenShift Container Platform. The example configures an Apache authentication proxy for OpenShift Container Platform by using the request header identity provider. ## Custom proxy configuration {#identity-provider-proxy-custom-configuration_configuring-request-header-identity-provider} 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, but not required, to configure the Apache authentication proxy by using the request header identity provider. Other proxies can easily be used if the following requirements are met: - 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 by 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. - Requires the proxy URL for `https:///oauth/authorize` to end with `/authorize` with no trailing slash. - Ensures subpaths of the proxy authorize URL forward to matching subpaths under `https:///oauth/authorize`. > [!NOTE] > The `https://` address is the route to the OAuth server and can be obtained by running `oc get route -n openshift-authentication`. ## Configuring Apache authentication using the request header {#identity-provider-configuring-apache-request-header_configuring-request-header-identity-provider} Configure an Apache authentication proxy with the `mod_auth_gssapi` module for the request header identity provider. Use this example to set up a proxy that validates users and forwards trusted identity headers to OpenShift Container Platform. This proxy uses a client certificate to connect to the OAuth server, which is configured to trust the `X-Remote-User` header. **Prerequisites** - Obtain the `mod_auth_gssapi` module from the optional channel. For more information, see "Optional channel". - The following packages are installed on your local machine: - `httpd` - `mod_ssl` - `mod_session` - `apr-util-openssl` - `mod_auth_gssapi` **Procedure** 1. Generate a CA for validating requests that submit the trusted header. 2. Create an OpenShift Container Platform `ConfigMap` object containing the CA by running the following command: ```terminal $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config ``` 3. Optional: Apply the following YAML to create the config map. For example: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | ``` The certificate authority must be stored in the `ca.crt` key of the `ConfigMap` object. 4. Generate a client certificate for the proxy. You can generate this certificate by using any x509 certificate tooling. The client certificate must be signed by the CA you generated for validating requests that submit the trusted header. 5. Create the custom resource (CR) for your identity providers. 6. Create the certificate for the Apache configuration. The certificate that you specify as the `SSLProxyMachineCertificateFile` parameter value is the client certificate for the proxy that authenticates the proxy to the server. It must use `TLS Web Client Authentication` as the extended key type. 7. Create the Apache configuration. Use the following template to provide your required settings and values: > [!IMPORTANT] > Carefully review the template and customize the template contents to fit your environment. ```terminal LoadModule request_module modules/mod_request.so LoadModule auth_gssapi_module modules/mod_auth_gssapi.so # Some Apache configurations might require these modules. # LoadModule auth_form_module modules/mod_auth_form.so # LoadModule session_module modules/mod_session.so # Nothing needs to be served over HTTP. This virtual host simply redirects to # HTTPS. DocumentRoot /var/www/html RewriteEngine On RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R,L] # This needs to match the certificates you generated. See the CN and X509v3 # Subject Alternative Name in the output of: # openssl x509 -text -in /etc/pki/tls/certs/localhost.crt ServerName www.example.com DocumentRoot /var/www/html SSLEngine on SSLCertificateFile /etc/pki/tls/certs/localhost.crt SSLCertificateKeyFile /etc/pki/tls/private/localhost.key SSLCACertificateFile /etc/pki/CA/certs/ca.crt SSLProxyEngine on SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt # It is critical to enforce client certificates. Otherwise, requests can # spoof the X-Remote-User header by accessing the /oauth/authorize endpoint # directly. SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem # To use the challenging-proxy, an X-Csrf-Token must be present. RewriteCond %{REQUEST_URI} ^/challenging-proxy RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC] RewriteRule ^.* - [F,L] # Insert your backend server name/ip here. ProxyPass https:///oauth/authorize AuthName "SSO Login" # For Kerberos AuthType GSSAPI Require valid-user RequestHeader set X-Remote-User %{REMOTE_USER}s GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab # Enable the following if you want to allow users to fallback # to password based authentication when they do not have a client # configured to perform kerberos authentication. GssapiBasicAuth On # For ldap: # AuthBasicProvider ldap # AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?sub?(objectClass=*)" # Insert your backend server name/ip here. ProxyPass https:///oauth/authorize AuthName "SSO Login" AuthType GSSAPI Require valid-user RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab # Enable the following if you want to allow users to fallback # to password based authentication when they do not have a client # configured to perform kerberos authentication. GssapiBasicAuth On ErrorDocument 401 /login.html RequestHeader unset X-Remote-User ``` > [!NOTE] > The `https://` address is the route to the OAuth server and can be obtained by running `oc get route -n openshift-authentication`. 8. Update the `identityProviders` section of the custom resource (CR): ```yaml identityProviders: - name: requestheaderidp type: RequestHeader requestHeader: challengeURL: "https:///challenging-proxy/oauth/authorize?${query}" loginURL: "https:///login-proxy/oauth/authorize?${query}" ca: name: ca-config-map clientCommonNames: - my-auth-proxy headers: - X-Remote-User ``` **Verification** 1. Confirm that you can bypass the proxy when you supply the correct client certificate and header by running the following command: ```terminal $ curl -L -k -H "X-Remote-User: joe" \ --cert /etc/pki/tls/certs/authproxy.pem \ https:///oauth/token/request ``` 2. Confirm that requests that do not supply the client certificate fail by running the following command: ```terminal $ curl -L -k -H "X-Remote-User: joe" \ https:///oauth/token/request ``` 3. Confirm that the `challengeURL` redirect is active by running the following command: ```terminal $ curl -k -v -H 'X-Csrf-Token: 1' \ https:///oauth/authorize?client_id=openshift-challenging-client&response_type=token ``` Copy the `challengeURL` redirect to use in the next step. 4. Show a `401` response with a `WWW-Authenticate` basic challenge, a negotiate challenge, or both challenges by running the following command: ```terminal $ curl -k -v -H 'X-Csrf-Token: 1' \ ``` 5. If you generated a Kerberos ticket by using `kinit`, destroy it by running the following command: ```terminal $ kdestroy -c ``` Replace `` with the name of your Kerberos cache. 6. Log in to the OpenShift CLI (`oc`) with your Kerberos credentials by running the following command: ```terminal $ oc login -u ``` Enter your Kerberos username and password at the prompt. 7. Log out of the `oc` tool by running the following command: ```terminal $ oc logout ``` 8. Use your Kerberos credentials to get a ticket by running the following command: ```terminal $ kinit ``` Enter your Kerberos username and password at the prompt. 9. Confirm that you can log in to the `oc` tool by running the following command: ```terminal $ oc login ``` If your configuration is correct, you are logged in without entering separate credentials. **Additional resources** {._additional-resources} - [Optional channel](https://access.redhat.com/solutions/392003)