Configure a 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.

About identity providers in OpenShift Container Platform

By default, only a kubeadmin user exists on your cluster. To specify an identity provider, you must create a Custom Resource (CR) that describes that identity provider and add it to the cluster.

OpenShift Container Platform user names containing /, :, and % are not supported.

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.

You can also use the request header identity provider for advanced configurations such as SAML authentication.

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.

To redirect unauthenticated requests from clients expecting browser-based login flows:

  1. 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.

To redirect unauthenticated requests from clients expecting WWW-Authenticate challenges:

  1. 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.

The provider.challengeURL and provider.loginURL parameters can include the following tokens in the query portion of the URL:

If you expect unauthenticated requests to reach the OAuth server, a clientCA parameter MUST be set for this identity provider, so that incoming requests are checked for a valid client certificate before the request’s headers are checked for a user name. Otherwise, any direct request to the OAuth server can impersonate any identity from this provider, merely by setting a request header.

SSPI connection support on Microsoft Windows

Using SSPI connection support on Microsoft Windows is a Technology Preview feature. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for 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 on Red Hat Technology Preview features support scope, see https://access.redhat.com/support/offerings/techpreview/.

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 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 providers use OpenShift Container Platform ConfigMaps in the openshift-config namespace to contain the certificate authority bundle. These are primarily used to contain certificate bundles needed by the identity provider.

  • Define an OpenShift Container Platform ConfigMap containing the certificate authority by using the following command.

    $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config

Sample request header CR

The following Custom Resource (CR) shows the parameters and acceptable values for a request header identity provider.

Request header CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: requestheaderidp (1)
    mappingMethod: claim (2)
    type: RequestHeader
    requestHeader:
      challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" (3)
      loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" (4)
      ca: (5)
        name: ca-config-map
      clientCommonNames: (6)
      - my-auth-proxy
      headers: (7)
      - X-Remote-User
      - SSO-User
      emailHeaders: (8)
      - X-Remote-User-Email
      nameHeaders: (9)
      - X-Remote-User-Display-Name
      preferredUsernameHeaders: (10)
      - X-Remote-User-Login
1 This provider name is prefixed to the user name in the request header to form an identity name.
2 Controls how mappings are established between this provider’s identities and user objects.
3 Optional: URL to redirect unauthenticated /oauth/authorize requests to, that will authenticate browser-based clients and then proxy their request to https://<namespace_route>/oauth/authorize. The URL that proxies to https://<namespace_route>/oauth/authorize must end with /authorize (with no trailing slash), and also proxy subpaths, in order 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, then loginURL must be used.
4 Optional: URL to redirect unauthenticated /oauth/authorize requests to, that will authenticate clients which expect WWW-Authenticate challenges, and then proxy them to https://<namespace_route>/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, then challengeURL must be used.
5 Reference to an OpenShift Container Platform ConfigMap containing a PEM-encoded certificate bundle. Used as a trust anchor to validate the TLS certificates presented by the remote server.
6 Optional: 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 user names. If empty, any Common Name is allowed. Can only be used in combination with clientCA.
7 Header names to check, in order, for the user identity. The first header containing a value is used as the identity. Required, case-insensitive.
8 Header names to check, in order, for an email address. The first header containing a value is used as the email address. Optional, case-insensitive.
9 Header names to check, in order, for a display name. The first header containing a value is used as the display name. Optional, case-insensitive.
10 Header names to check, in order, for a preferred user name, if different than the immutable identity determined from the headers specified in headers. The first header containing a value is used as the preferred user name when provisioning. Optional, case-insensitive.

Adding an identity provider to your clusters

After you install your cluster, add an identity provider to it so your users can authenticate.

Prerequisites
  • Create an OpenShift Container Platform cluster.

  • Create the Custom Resource (CR) for your identity providers.

  • You must be logged in as an administrator.

Procedure
  1. Apply the defined CR:

    $ oc apply -f </path/to/CR>
  2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

    $ oc login -u <username>
  3. Confirm that the user logged in successfully, and display the user name.

    $ oc whoami