Chapter 7. Configuring identity providers 7.1. Configuring an htpasswd identity provider Configure the htpasswd identity provider to allow users to log in to OpenShift Container Platform with credentials from an htpasswd file. To define an htpasswd identity provider, perform the following tasks: Create an htpasswd file to store the user and password information. Create a secret to represent the htpasswd file. Define an htpasswd identity provider resource that references the secret. Apply the resource to the default OAuth configuration to add the identity provider. 7.1.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.1.2. About htpasswd authentication Using htpasswd authentication in OpenShift Container Platform allows you to identify users based on an htpasswd file. An htpasswd file is a flat file that contains the user name and hashed password for each user. You can use the htpasswd utility to create this file. 7.1.3. Creating the htpasswd file See one of the following sections for instructions about how to create the htpasswd file: Creating an htpasswd file using Linux Creating an htpasswd file using Windows 7.1.3.1. Creating an htpasswd file using Linux To use the htpasswd identity provider, you must generate a flat file that contains the user names and passwords for your cluster by using htpasswd . Prerequisites Have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by installing the httpd-tools package. Procedure Create or update your flat file with a user name and hashed password: USD htpasswd -c -B -b </path/to/users.htpasswd> <username> <password> The command generates a hashed version of the password. For example: USD htpasswd -c -B -b users.htpasswd <username> <password> Example output Adding password for user user1 Continue to add or update credentials to the file: USD htpasswd -B -b </path/to/users.htpasswd> <user_name> <password> 7.1.3.2. Creating an htpasswd file using Windows To use the htpasswd identity provider, you must generate a flat file that contains the user names and passwords for your cluster by using htpasswd . Prerequisites Have access to htpasswd.exe . This file is included in the \bin directory of many Apache httpd distributions. Procedure Create or update your flat file with a user name and hashed password: > htpasswd.exe -c -B -b <\path\to\users.htpasswd> <username> <password> The command generates a hashed version of the password. For example: > htpasswd.exe -c -B -b users.htpasswd <username> <password> Example output Adding password for user user1 Continue to add or update credentials to the file: > htpasswd.exe -b <\path\to\users.htpasswd> <username> <password> 7.1.4. Creating the htpasswd secret To use the htpasswd identity provider, you must define a secret that contains the htpasswd user file. Prerequisites Create an htpasswd file. Procedure Create a Secret object that contains the htpasswd users file: USD oc create secret generic htpass-secret --from-file=htpasswd=<path_to_users.htpasswd> -n openshift-config 1 1 The secret key containing the users file for the --from-file argument must be named htpasswd , as shown in the above command. Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: htpass-secret namespace: openshift-config type: Opaque data: htpasswd: <base64_encoded_htpasswd_file_contents> 7.1.5. Sample htpasswd CR The following custom resource (CR) shows the parameters and acceptable values for an htpasswd identity provider. htpasswd CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: my_htpasswd_provider 1 mappingMethod: claim 2 type: HTPasswd htpasswd: fileData: name: htpass-secret 3 1 This provider name is prefixed to provider user names to form an identity name. 2 Controls how mappings are established between this provider's identities and User objects. 3 An existing secret containing a file generated using htpasswd . Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.1.6. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.1.7. Updating users for an htpasswd identity provider You can add or remove users from an existing htpasswd identity provider. Prerequisites You have created a Secret object that contains the htpasswd user file. This procedure assumes that it is named htpass-secret . You have configured an htpasswd identity provider. This procedure assumes that it is named my_htpasswd_provider . You have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by installing the httpd-tools package. You have cluster administrator privileges. Procedure Retrieve the htpasswd file from the htpass-secret Secret object and save the file to your file system: USD oc get secret htpass-secret -ojsonpath={.data.htpasswd} -n openshift-config | base64 --decode > users.htpasswd Add or remove users from the users.htpasswd file. To add a new user: USD htpasswd -bB users.htpasswd <username> <password> Example output Adding password for user <username> To remove an existing user: USD htpasswd -D users.htpasswd <username> Example output Deleting password for user <username> Replace the htpass-secret Secret object with the updated users in the users.htpasswd file: USD oc create secret generic htpass-secret --from-file=htpasswd=users.htpasswd --dry-run=client -o yaml -n openshift-config | oc replace -f - Tip You can alternatively apply the following YAML to replace the secret: apiVersion: v1 kind: Secret metadata: name: htpass-secret namespace: openshift-config type: Opaque data: htpasswd: <base64_encoded_htpasswd_file_contents> If you removed one or more users, you must additionally remove existing resources for each user. Delete the User object: USD oc delete user <username> Example output user.user.openshift.io "<username>" deleted Be sure to remove the user, otherwise the user can continue using their token as long as it has not expired. Delete the Identity object for the user: USD oc delete identity my_htpasswd_provider:<username> Example output identity.user.openshift.io "my_htpasswd_provider:<username>" deleted 7.1.8. Configuring identity providers using the web console Configure your identity provider (IDP) through the web console instead of the CLI. Prerequisites You must be logged in to the web console as a cluster administrator. Procedure Navigate to Administration Cluster Settings . Under the Configuration tab, click OAuth . Under the Identity Providers section, select your identity provider from the Add drop-down menu. Note You can specify multiple IDPs through the web console without overwriting existing IDPs. 7.2. Configuring a Keystone identity provider Configure the keystone identity provider to integrate your OpenShift Container Platform cluster with Keystone to enable shared authentication with an OpenStack Keystone v3 server configured to store users in an internal database. This configuration allows users to log in to OpenShift Container Platform with their Keystone credentials. 7.2.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.2.2. About Keystone authentication Keystone is an OpenStack project that provides identity, token, catalog, and policy services. You can configure the integration with Keystone so that the new OpenShift Container Platform users are based on either the Keystone user names or unique Keystone IDs. With both methods, users log in by entering their Keystone user name and password. Basing the OpenShift Container Platform users on the Keystone ID is more secure because if you delete a Keystone user and create a new Keystone user with that user name, the new user might have access to the old user's resources. 7.2.3. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object that contains the key and certificate by using the following command: USD oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: kubernetes.io/tls data: tls.crt: <base64_encoded_cert> tls.key: <base64_encoded_key> 7.2.4. Creating a config map Identity providers use OpenShift Container Platform 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. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.2.5. Sample Keystone CR The following custom resource (CR) shows the parameters and acceptable values for a Keystone identity provider. Keystone CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: keystoneidp 1 mappingMethod: claim 2 type: Keystone keystone: domainName: default 3 url: https://keystone.example.com:5000 4 ca: 5 name: ca-config-map tlsClientCert: 6 name: client-cert-secret tlsClientKey: 7 name: client-key-secret 1 This provider name is prefixed to provider user names to form an identity name. 2 Controls how mappings are established between this provider's identities and User objects. 3 Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported. 4 The URL to use to connect to the Keystone server (required). This must use https. 5 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. 6 Optional: Reference to an OpenShift Container Platform Secret object containing the client certificate to present when making requests to the configured URL. 7 Reference to an OpenShift Container Platform Secret object containing the key for the client certificate. Required if tlsClientCert is specified. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.2.6. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.3. Configuring an LDAP identity provider Configure the ldap identity provider to validate user names and passwords against an LDAPv3 server, using simple bind authentication. 7.3.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.3.2. About LDAP authentication During authentication, the LDAP directory is searched for an entry that matches the provided user name. If a single unique match is found, a simple bind is attempted using the distinguished name (DN) of the entry plus the provided password. These are the steps taken: Generate a search filter by combining the attribute and filter in the configured url with the user-provided user name. Search the directory using the generated filter. If the search does not return exactly one entry, deny access. Attempt to bind to the LDAP server using the DN of the entry retrieved from the search, and the user-provided password. If the bind is unsuccessful, deny access. If the bind is successful, build an identity using the configured attributes as the identity, email address, display name, and preferred user name. The configured url is an RFC 2255 URL, which specifies the LDAP host and search parameters to use. The syntax of the URL is: For this URL: URL component Description ldap For regular LDAP, use the string ldap . For secure LDAP (LDAPS), use ldaps instead. host:port The name and port of the LDAP server. Defaults to localhost:389 for ldap and localhost:636 for LDAPS. basedn The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but it could also specify a subtree in the directory. attribute The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid . It is recommended to choose an attribute that will be unique across all entries in the subtree you will be using. scope The scope of the search. Can be either one or sub . If the scope is not provided, the default is to use a scope of sub . filter A valid LDAP search filter. If not provided, defaults to (objectClass=*) When doing searches, the attribute, filter, and provided user name are combined to create a search filter that looks like: For example, consider a URL of: When a client attempts to connect using a user name of bob , the resulting search filter will be (&(enabled=true)(cn=bob)) . If the LDAP directory requires authentication to search, specify a bindDN and bindPassword to use to perform the entry search. 7.3.3. Creating the LDAP secret To use the identity provider, you must define an OpenShift Container Platform Secret object that contains the bindPassword field. Procedure Create a Secret object that contains the bindPassword field: USD oc create secret generic ldap-secret --from-literal=bindPassword=<secret> -n openshift-config 1 1 The secret key containing the bindPassword for the --from-literal argument must be called bindPassword . Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: ldap-secret namespace: openshift-config type: Opaque data: bindPassword: <base64_encoded_bind_password> 7.3.4. Creating a config map Identity providers use OpenShift Container Platform 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. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.3.5. Sample LDAP CR The following custom resource (CR) shows the parameters and acceptable values for an LDAP identity provider. LDAP CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: ldapidp 1 mappingMethod: claim 2 type: LDAP ldap: attributes: id: 3 - dn email: 4 - mail name: 5 - cn preferredUsername: 6 - uid bindDN: "" 7 bindPassword: 8 name: ldap-secret ca: 9 name: ca-config-map insecure: false 10 url: "ldaps://ldaps.example.com/ou=users,dc=acme,dc=com?uid" 11 1 This provider name is prefixed to the returned user ID to form an identity name. 2 Controls how mappings are established between this provider's identities and User objects. 3 List of attributes to use as the identity. First non-empty attribute is used. At least one attribute is required. If none of the listed attribute have a value, authentication fails. Defined attributes are retrieved as raw, allowing for binary values to be used. 4 List of attributes to use as the email address. First non-empty attribute is used. 5 List of attributes to use as the display name. First non-empty attribute is used. 6 List of attributes to use as the preferred user name when provisioning a user for this identity. First non-empty attribute is used. 7 Optional DN to use to bind during the search phase. Must be set if bindPassword is defined. 8 Optional reference to an OpenShift Container Platform Secret object containing the bind password. Must be set if bindDN is defined. 9 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. Only used when insecure is false . 10 When true , no TLS connection is made to the server. When false , ldaps:// URLs connect using TLS, and ldap:// URLs are upgraded to TLS. This must be set to false when ldaps:// URLs are in use, as these URLs always attempt to connect using TLS. 11 An RFC 2255 URL which specifies the LDAP host and search parameters to use. Note To whitelist users for an LDAP integration, use the lookup mapping method. Before a login from LDAP would be allowed, a cluster administrator must create an Identity object and a User object for each LDAP user. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.3.6. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.4. Configuring a basic authentication identity provider Configure the basic-authentication identity provider for users to log in to OpenShift Container Platform with credentials validated against a remote identity provider. Basic authentication is a generic back-end integration mechanism. 7.4.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.4.2. About basic authentication Basic authentication is a generic back-end integration mechanism that allows users to log in to OpenShift Container Platform with credentials validated against a remote identity provider. Because basic authentication is generic, you can use this identity provider for advanced authentication configurations. Important Basic authentication must use an HTTPS connection to the remote server to prevent potential snooping of the user ID and password and man-in-the-middle attacks. With basic authentication configured, users send their user name and password to OpenShift Container Platform, which then validates those credentials against a remote server by making a server-to-server request, passing the credentials as a basic authentication header. This requires users to send their credentials to OpenShift Container Platform during login. Note This only works for user name/password login mechanisms, and OpenShift Container Platform must be able to make network requests to the remote authentication server. User names and passwords are validated against a remote URL that is protected by basic authentication and returns JSON. A 401 response indicates failed authentication. A non- 200 status, or the presence of a non-empty "error" key, indicates an error: {"error":"Error message"} A 200 status with a sub (subject) key indicates success: {"sub":"userid"} 1 1 The subject must be unique to the authenticated user and must not be able to be modified. A successful response can optionally provide additional data, such as: A display name using the name key. For example: {"sub":"userid", "name": "User Name", ...} An email address using the email key. For example: {"sub":"userid", "email":"user@example.com", ...} A preferred user name using the preferred_username key. This is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the OpenShift Container Platform user for the authenticated identity. For example: {"sub":"014fbff9a07c", "preferred_username":"bob", ...} 7.4.3. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object that contains the key and certificate by using the following command: USD oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: kubernetes.io/tls data: tls.crt: <base64_encoded_cert> tls.key: <base64_encoded_key> 7.4.4. Creating a config map Identity providers use OpenShift Container Platform 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. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.4.5. Sample basic authentication CR The following custom resource (CR) shows the parameters and acceptable values for a basic authentication identity provider. Basic authentication CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: basicidp 1 mappingMethod: claim 2 type: BasicAuth basicAuth: url: https://www.example.com/remote-idp 3 ca: 4 name: ca-config-map tlsClientCert: 5 name: client-cert-secret tlsClientKey: 6 name: client-key-secret 1 This provider name is prefixed to the returned user ID to form an identity name. 2 Controls how mappings are established between this provider's identities and User objects. 3 URL accepting credentials in Basic authentication headers. 4 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. 5 Optional: Reference to an OpenShift Container Platform Secret object containing the client certificate to present when making requests to the configured URL. 6 Reference to an OpenShift Container Platform Secret object containing the key for the client certificate. Required if tlsClientCert is specified. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.4.6. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.4.7. Example Apache HTTPD configuration for basic identity providers The basic identify provider (IDP) configuration in OpenShift Container Platform 4 requires that the IDP server respond with JSON for success and failures. You can use CGI scripting in Apache HTTPD to accomplish this. This section provides examples. Example /etc/httpd/conf.d/login.conf Example /var/www/cgi-bin/login.cgi Example /var/www/cgi-bin/fail.cgi 7.4.7.1. File requirements These are the requirements for the files you create on an Apache HTTPD web server: login.cgi and fail.cgi must be executable ( chmod +x ). login.cgi and fail.cgi must have proper SELinux contexts if SELinux is enabled: restorecon -RFv /var/www/cgi-bin , or ensure that the context is httpd_sys_script_exec_t using ls -laZ . login.cgi is only executed if your user successfully logs in per Require and Auth directives. fail.cgi is executed if the user fails to log in, resulting in an HTTP 401 response. 7.4.8. Basic authentication troubleshooting The most common issue relates to network connectivity to the backend server. For simple debugging, run curl commands on the master. To test for a successful login, replace the <user> and <password> in the following example command with valid credentials. To test an invalid login, replace them with false credentials. USD curl --cacert /path/to/ca.crt --cert /path/to/client.crt --key /path/to/client.key -u <user>:<password> -v https://www.example.com/remote-idp Successful responses A 200 status with a sub (subject) key indicates success: {"sub":"userid"} The subject must be unique to the authenticated user, and must not be able to be modified. A successful response can optionally provide additional data, such as: A display name using the name key: {"sub":"userid", "name": "User Name", ...} An email address using the email key: {"sub":"userid", "email":"user@example.com", ...} A preferred user name using the preferred_username key: {"sub":"014fbff9a07c", "preferred_username":"bob", ...} The preferred_username key is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the OpenShift Container Platform user for the authenticated identity. Failed responses A 401 response indicates failed authentication. A non- 200 status or the presence of a non-empty "error" key indicates an error: {"error":"Error message"} 7.5. Configuring a request header identity provider 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. 7.5.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.5.2. 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. Note You can also use the request header identity provider for advanced configurations such as the community-supported SAML authentication . Note that 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 . 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 . 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 . The provider.challengeURL and provider.loginURL parameters can include the following tokens in the query portion of the URL: USD{url} is replaced with the current URL, escaped to be safe in a query parameter. For example: https://www.example.com/sso-login?then=USD{url} USD{query} is replaced with the current query string, unescaped. For example: https://www.example.com/auth-proxy/oauth/authorize?USD{query} Important As of OpenShift Container Platform 4.1, your proxy must support mutual TLS. 7.5.2.1. SSPI connection support on Microsoft Windows Important Using SSPI 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 . 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 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. 7.5.3. Creating a config map Identity providers use OpenShift Container Platform 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. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.5.4. 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?USD{query}" 3 loginURL: "https://www.example.com/login-proxy/oauth/authorize?USD{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. USD{url} is replaced with the current URL, escaped to be safe in a query parameter. USD{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 . USD{url} is replaced with the current URL, escaped to be safe in a query parameter. USD{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 object containing a PEM-encoded certificate bundle. Used as a trust anchor to validate the 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. 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 ca . 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. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.5.5. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.5.6. Example Apache authentication configuration using request header This example configures an Apache authentication proxy for the OpenShift Container Platform using the request header identity provider. 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 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 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 . Configuring Apache authentication using request header This example uses the mod_auth_gssapi module to configure an Apache authentication proxy using the request header identity provider. Prerequisites Obtain the mod_auth_gssapi module from the Optional channel . You must have the following packages installed on your local machine: httpd mod_ssl mod_session apr-util-openssl mod_auth_gssapi Generate a CA for validating requests that submit the trusted header. Define an OpenShift Container Platform ConfigMap object containing the CA. This is done by running: USD oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config 1 1 The CA must be stored in the ca.crt key of the ConfigMap object. Tip You can alternatively apply the following YAML to create the config map: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 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. Create the custom resource (CR) for your identity providers. Procedure This proxy uses a client certificate to connect to the OAuth server, which is configured to trust the X-Remote-User header. Create the certificate for the Apache configuration. The certificate that you specify as the SSLProxyMachineCertificateFile parameter value is the proxy's client certificate that is used to authenticate the proxy to the server. It must use TLS Web Client Authentication as the extended key type. Create the Apache configuration. Use the following template to provide your required settings and values: Important Carefully review the template and customize its contents to fit your environment. 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 . Update the identityProviders stanza in the custom resource (CR): identityProviders: - name: requestheaderidp type: RequestHeader requestHeader: challengeURL: "https://<namespace_route>/challenging-proxy/oauth/authorize?USD{query}" loginURL: "https://<namespace_route>/login-proxy/oauth/authorize?USD{query}" ca: name: ca-config-map clientCommonNames: - my-auth-proxy headers: - X-Remote-User Verify the configuration. Confirm that you can bypass the proxy by requesting a token by supplying the correct client certificate and header: # curl -L -k -H "X-Remote-User: joe" \ --cert /etc/pki/tls/certs/authproxy.pem \ https://<namespace_route>/oauth/token/request Confirm that requests that do not supply the client certificate fail by requesting a token without the certificate: # curl -L -k -H "X-Remote-User: joe" \ https://<namespace_route>/oauth/token/request Confirm that the challengeURL redirect is active: # curl -k -v -H 'X-Csrf-Token: 1' \ https://<namespace_route>/oauth/authorize?client_id=openshift-challenging-client&response_type=token Copy the challengeURL redirect to use in the step. Run this command to show a 401 response with a WWW-Authenticate basic challenge, a negotiate challenge, or both challenges: # curl -k -v -H 'X-Csrf-Token: 1' \ <challengeURL_redirect + query> Test logging in to the OpenShift CLI ( oc ) with and without using a Kerberos ticket: If you generated a Kerberos ticket by using kinit , destroy it: # kdestroy -c cache_name 1 1 Make sure to provide the name of your Kerberos cache. Log in to the oc tool by using your Kerberos credentials: # oc login -u <username> Enter your Kerberos password at the prompt. Log out of the oc tool: # oc logout Use your Kerberos credentials to get a ticket: # kinit Enter your Kerberos user name and password at the prompt. Confirm that you can log in to the oc tool: # oc login If your configuration is correct, you are logged in without entering separate credentials. 7.6. Configuring a GitHub or GitHub Enterprise identity provider Configure the github identity provider to validate user names and passwords against GitHub or GitHub Enterprise's OAuth authentication server. OAuth facilitates a token exchange flow between OpenShift Container Platform and GitHub or GitHub Enterprise. You can use the GitHub integration to connect to either GitHub or GitHub Enterprise. For GitHub Enterprise integrations, you must provide the hostname of your instance and can optionally provide a ca certificate bundle to use in requests to the server. Note The following steps apply to both GitHub and GitHub Enterprise unless noted. 7.6.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.6.2. About GitHub authentication Configuring GitHub authentication allows users to log in to OpenShift Container Platform with their GitHub credentials. To prevent anyone with any GitHub user ID from logging in to your OpenShift Container Platform cluster, you can restrict access to only those in specific GitHub organizations. 7.6.3. Registering a GitHub application To use GitHub or GitHub Enterprise as an identity provider, you must register an application to use. Procedure Register an application on GitHub: For GitHub, click Settings Developer settings OAuth Apps Register a new OAuth application . For GitHub Enterprise, go to your GitHub Enterprise home page and then click Settings Developer settings Register a new application . Enter an application name, for example My OpenShift Install . Enter a homepage URL, such as https://oauth-openshift.apps.<cluster-name>.<cluster-domain> . Optional: Enter an application description. Enter the authorization callback URL, where the end of the URL contains the identity provider name : For example: Click Register application . GitHub provides a client ID and a client secret. You need these values to complete the identity provider configuration. 7.6.4. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object containing a string by using the following command: USD oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret> You can define a Secret object containing the contents of a file, such as a certificate file, by using the following command: USD oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config 7.6.5. Creating a config map Identity providers use OpenShift Container Platform 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. Note This procedure is only required for GitHub Enterprise. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.6.6. Sample GitHub CR The following custom resource (CR) shows the parameters and acceptable values for a GitHub identity provider. GitHub CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: githubidp 1 mappingMethod: claim 2 type: GitHub github: ca: 3 name: ca-config-map clientID: {...} 4 clientSecret: 5 name: github-secret hostname: ... 6 organizations: 7 - myorganization1 - myorganization2 teams: 8 - myorganization1/team-a - myorganization2/team-b 1 This provider name is prefixed to the GitHub numeric user ID to form an identity name. It is also used to build the callback URL. 2 Controls how mappings are established between this provider's identities and User objects. 3 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. Only for use in GitHub Enterprise with a non-publicly trusted root certificate. 4 The client ID of a registered GitHub OAuth application . The application must be configured with a callback URL of https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name> . 5 Reference to an OpenShift Container Platform Secret object containing the client secret issued by GitHub. 6 For GitHub Enterprise, you must provide the hostname of your instance, such as example.com . This value must match the GitHub Enterprise hostname value in in the /setup/settings file and cannot include a port number. If this value is not set, then either teams or organizations must be defined. For GitHub, omit this parameter. 7 The list of organizations. Either the organizations or teams field must be set unless the hostname field is set, or if mappingMethod is set to lookup . Cannot be used in combination with the teams field. 8 The list of teams. Either the teams or organizations field must be set unless the hostname field is set, or if mappingMethod is set to lookup . Cannot be used in combination with the organizations field. Note If organizations or teams is specified, only GitHub users that are members of at least one of the listed organizations will be allowed to log in. If the GitHub OAuth application configured in clientID is not owned by the organization, an organization owner must grant third-party access to use this option. This can be done during the first GitHub login by the organization's administrator, or from the GitHub organization settings. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.6.7. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Obtain a token from the OAuth server. As long as the kubeadmin user has been removed, the oc login command provides instructions on how to access a web page where you can retrieve the token. 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. USD oc login --token=<token> Note This identity provider does not support logging in with a user name and password. Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.7. Configuring a GitLab identity provider Configure the gitlab identity provider using GitLab.com or any other GitLab instance as an identity provider. 7.7.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.7.2. About GitLab authentication Configuring GitLab authentication allows users to log in to OpenShift Container Platform with their GitLab credentials. If you use GitLab version 7.7.0 to 11.0, you connect using the OAuth integration . If you use GitLab version 11.1 or later, you can use OpenID Connect (OIDC) to connect instead of OAuth. 7.7.3. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object containing a string by using the following command: USD oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret> You can define a Secret object containing the contents of a file, such as a certificate file, by using the following command: USD oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config 7.7.4. Creating a config map Identity providers use OpenShift Container Platform 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. Note This procedure is only required for GitHub Enterprise. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.7.5. Sample GitLab CR The following custom resource (CR) shows the parameters and acceptable values for a GitLab identity provider. GitLab CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: gitlabidp 1 mappingMethod: claim 2 type: GitLab gitlab: clientID: {...} 3 clientSecret: 4 name: gitlab-secret url: https://gitlab.com 5 ca: 6 name: ca-config-map 1 This provider name is prefixed to the GitLab numeric user ID to form an identity name. It is also used to build the callback URL. 2 Controls how mappings are established between this provider's identities and User objects. 3 The client ID of a registered GitLab OAuth application . The application must be configured with a callback URL of https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name> . 4 Reference to an OpenShift Container Platform Secret object containing the client secret issued by GitLab. 5 The host URL of a GitLab provider. This could either be https://gitlab.com/ or any other self hosted instance of GitLab. 6 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.7.6. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Log in to the cluster as a user from your identity provider, entering the password when prompted. USD oc login -u <username> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.8. Configuring a Google identity provider Configure the google identity provider using the Google OpenID Connect integration . 7.8.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.8.2. About Google authentication Using Google as an identity provider allows any Google user to authenticate to your server. You can limit authentication to members of a specific hosted domain with the hostedDomain configuration attribute. Note Using Google as an identity provider requires users to get a token using <namespace_route>/oauth/token/request to use with command-line tools. 7.8.3. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object containing a string by using the following command: USD oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret> You can define a Secret object containing the contents of a file, such as a certificate file, by using the following command: USD oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config 7.8.4. Sample Google CR The following custom resource (CR) shows the parameters and acceptable values for a Google identity provider. Google CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: googleidp 1 mappingMethod: claim 2 type: Google google: clientID: {...} 3 clientSecret: 4 name: google-secret hostedDomain: "example.com" 5 1 This provider name is prefixed to the Google numeric user ID 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 registered Google project . The project must be configured with a redirect URI of https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name> . 4 Reference to an OpenShift Container Platform Secret object containing the client secret issued by Google. 5 A hosted domain used to restrict sign-in accounts. Optional if the lookup mappingMethod is used. If empty, any Google account is allowed to authenticate. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.8.5. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Obtain a token from the OAuth server. As long as the kubeadmin user has been removed, the oc login command provides instructions on how to access a web page where you can retrieve the token. 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. USD oc login --token=<token> Note This identity provider does not support logging in with a user name and password. Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.9. Configuring an OpenID Connect identity provider Configure the oidc identity provider to integrate with an OpenID Connect identity provider using an Authorization Code Flow . 7.9.1. 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. Note OpenShift Container Platform user names containing / , : , and % are not supported. 7.9.2. About OpenID Connect authentication The Authentication Operator in OpenShift Container Platform requires that the configured OpenID Connect identity provider implements the OpenID Connect Discovery specification. Note ID Token and UserInfo decryptions are not supported. By default, the openid scope is requested. If required, extra scopes can be specified in the extraScopes field. Claims are read from the JWT id_token returned from the OpenID identity provider and, if specified, from the JSON returned by the UserInfo URL. At least one claim must be configured to use as the user's identity. The standard identity claim is sub . You can also indicate which claims to use as the user's preferred user name, display name, and email address. If multiple claims are specified, the first one with a non-empty value is used. The following table lists the standard claims: Claim Description sub Short for "subject identifier." The remote identity for the user at the issuer. preferred_username The preferred user name when provisioning a user. A shorthand name that the user wants to be referred to as, such as janedoe . Typically a value that corresponding to the user's login or username in the authentication system, such as username or email. email Email address. name Display name. See the OpenID claims documentation for more information. Note Unless your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, users must get a token from <namespace_route>/oauth/token/request to use with command-line tools. 7.9.3. Supported OIDC providers Red Hat tests and supports specific OpenID Connect (OIDC) providers with OpenShift Container Platform. The following OpenID Connect (OIDC) providers are tested and supported with OpenShift Container Platform. Using an OIDC provider that is not on the following list might work with OpenShift Container Platform, but the provider was not tested by Red Hat and therefore is not supported by Red Hat. GitLab Google Keycloak Okta Ping Identity Red Hat Single Sign-On 7.9.4. Creating the secret Identity providers use OpenShift Container Platform Secret objects in the openshift-config namespace to contain the client secret, client certificates, and keys. Procedure Create a Secret object containing a string by using the following command: USD oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config Tip You can alternatively apply the following YAML to create the secret: apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret> You can define a Secret object containing the contents of a file, such as a certificate file, by using the following command: USD oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config 7.9.5. Creating a config map Identity providers use OpenShift Container Platform 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. Note This procedure is only required for GitHub Enterprise. Procedure Define an OpenShift Container Platform 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. USD 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: apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM> 7.9.6. Sample OpenID Connect CRs The following custom resources (CRs) show the parameters and acceptable values for an OpenID Connect identity provider. If you must specify a custom certificate bundle, extra scopes, extra authorization request parameters, or a userInfo URL, use the full OpenID Connect CR. Standard OpenID Connect CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: oidcidp 1 mappingMethod: claim 2 type: OpenID openID: clientID: ... 3 clientSecret: 4 name: idp-secret claims: 5 preferredUsername: - preferred_username name: - name email: - email groups: - groups issuer: https://www.idp-issuer.com 6 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 OpenShift Container Platform 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 Issuer Identifier described in the OpenID spec. Must use https without query or fragment component. Full OpenID Connect CR apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: oidcidp mappingMethod: claim type: OpenID openID: clientID: ... clientSecret: name: idp-secret ca: 1 name: ca-config-map extraScopes: 2 - email - profile extraAuthorizeParameters: 3 include_granted_scopes: "true" claims: preferredUsername: 4 - preferred_username - email name: 5 - nickname - given_name - name email: 6 - custom_email_claim - email groups: 7 - groups issuer: https://www.idp-issuer.com 1 Optional: Reference to an OpenShift Container Platform 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 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 OpenShift Container Platform upon user login. The first non-empty claim is used. Additional resources See Identity provider parameters for information on parameters, such as mappingMethod , that are common to all identity providers. 7.9.7. Adding an identity provider to your cluster 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 Apply the defined CR: USD oc apply -f </path/to/CR> 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. Obtain a token from the OAuth server. As long as the kubeadmin user has been removed, the oc login command provides instructions on how to access a web page where you can retrieve the token. 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. USD oc login --token=<token> Note 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 OpenShift Container Platform, you can log in by using the following command, which prompts for your user name and password: USD oc login -u <identity_provider_username> --server=<api_server_url_and_port> Confirm that the user logged in successfully, and display the user name. USD oc whoami 7.9.8. Configuring identity providers using the web console Configure your identity provider (IDP) through the web console instead of the CLI. Prerequisites You must be logged in to the web console as a cluster administrator. Procedure Navigate to Administration Cluster Settings . Under the Configuration tab, click OAuth . Under the Identity Providers section, select your identity provider from the Add drop-down menu. Note You can specify multiple IDPs through the web console without overwriting existing IDPs.

Commands:
htpasswd -c -B -b </path/to/users.htpasswd> <username> <password>
htpasswd -c -B -b users.htpasswd <username> <password>
Adding password for user user1
htpasswd -B -b </path/to/users.htpasswd> <user_name> <password>
> htpasswd.exe -c -B -b <\path\to\users.htpasswd> <username> <password>
> htpasswd.exe -c -B -b users.htpasswd <username> <password>
Adding password for user user1
> htpasswd.exe -b <\path\to\users.htpasswd> <username> <password>
oc create secret generic htpass-secret --from-file=htpasswd=<path_to_users.htpasswd> -n openshift-config 1
apiVersion: v1 kind: Secret metadata: name: htpass-secret namespace: openshift-config type: Opaque data: htpasswd: <base64_encoded_htpasswd_file_contents>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: my_htpasswd_provider 1 mappingMethod: claim 2 type: HTPasswd htpasswd: fileData: name: htpass-secret 3
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
oc get secret htpass-secret -ojsonpath={.data.htpasswd} -n openshift-config | base64 --decode > users.htpasswd
htpasswd -bB users.htpasswd <username> <password>
Adding password for user <username>
htpasswd -D users.htpasswd <username>
Deleting password for user <username>
oc create secret generic htpass-secret --from-file=htpasswd=users.htpasswd --dry-run=client -o yaml -n openshift-config | oc replace -f -
apiVersion: v1 kind: Secret metadata: name: htpass-secret namespace: openshift-config type: Opaque data: htpasswd: <base64_encoded_htpasswd_file_contents>
oc delete user <username>
user.user.openshift.io "<username>" deleted
oc delete identity my_htpasswd_provider:<username>
identity.user.openshift.io "my_htpasswd_provider:<username>" deleted
oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: kubernetes.io/tls data: tls.crt: <base64_encoded_cert> tls.key: <base64_encoded_key>
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: keystoneidp 1 mappingMethod: claim 2 type: Keystone keystone: domainName: default 3 url: https://keystone.example.com:5000 4 ca: 5 name: ca-config-map tlsClientCert: 6 name: client-cert-secret tlsClientKey: 7 name: client-key-secret
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
ldap://host:port/basedn?attribute?scope?filter
(&(<filter>)(<attribute>=<username>))
ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true)
oc create secret generic ldap-secret --from-literal=bindPassword=<secret> -n openshift-config 1
apiVersion: v1 kind: Secret metadata: name: ldap-secret namespace: openshift-config type: Opaque data: bindPassword: <base64_encoded_bind_password>
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: ldapidp 1 mappingMethod: claim 2 type: LDAP ldap: attributes: id: 3 - dn email: 4 - mail name: 5 - cn preferredUsername: 6 - uid bindDN: "" 7 bindPassword: 8 name: ldap-secret ca: 9 name: ca-config-map insecure: false 10 url: "ldaps://ldaps.example.com/ou=users,dc=acme,dc=com?uid" 11
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
error: Error message
{"sub":"userid"} 1
{"sub":"userid", "name": "User Name", ...}
{"sub":"userid", "email":"user@example.com", ...}
{"sub":"014fbff9a07c", "preferred_username":"bob", ...}
oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: kubernetes.io/tls data: tls.crt: <base64_encoded_cert> tls.key: <base64_encoded_key>
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: basicidp 1 mappingMethod: claim 2 type: BasicAuth basicAuth: url: https://www.example.com/remote-idp 3 ca: 4 name: ca-config-map tlsClientCert: 5 name: client-cert-secret tlsClientKey: 6 name: client-key-secret
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
<VirtualHost *:443> # CGI Scripts in here DocumentRoot /var/www/cgi-bin # SSL Directives SSLEngine on SSLCipherSuite PROFILE=SYSTEM SSLProxyCipherSuite PROFILE=SYSTEM SSLCertificateFile /etc/pki/tls/certs/localhost.crt SSLCertificateKeyFile /etc/pki/tls/private/localhost.key # Configure HTTPD to execute scripts ScriptAlias /basic /var/www/cgi-bin # Handles a failed login attempt ErrorDocument 401 /basic/fail.cgi # Handles authentication <Location /basic/login.cgi> AuthType Basic AuthName "Please Log In" AuthBasicProvider file AuthUserFile /etc/httpd/conf/passwords Require valid-user </Location> </VirtualHost>
#!/bin/bash echo "Content-Type: application/json" echo "" echo '{"sub":"userid", "name":"'USDREMOTE_USER'"}' exit 0
#!/bin/bash echo "Content-Type: application/json" echo "" echo '{"error": "Login failure"}' exit 0
curl --cacert /path/to/ca.crt --cert /path/to/client.crt --key /path/to/client.key -u <user>:<password> -v https://www.example.com/remote-idp
sub: userid
{"sub":"userid", "name": "User Name", ...}
{"sub":"userid", "email":"user@example.com", ...}
{"sub":"014fbff9a07c", "preferred_username":"bob", ...}
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
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?USD{query}" 3 loginURL: "https://www.example.com/login-proxy/oauth/authorize?USD{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
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config 1
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
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. <VirtualHost *:80> DocumentRoot /var/www/html RewriteEngine On RewriteRule ^(.*)USD https://%{HTTP_HOST}USD1 [R,L] </VirtualHost> <VirtualHost *:443> # 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} ^USD [NC] RewriteRule ^.* - [F,L] <Location /challenging-proxy/oauth/authorize> # Insert your backend server name/ip here. ProxyPass https://<namespace_route>/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=*)" </Location> <Location /login-proxy/oauth/authorize> # Insert your backend server name/ip here. ProxyPass https://<namespace_route>/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 </Location> </VirtualHost> RequestHeader unset X-Remote-User
identityProviders: - name: requestheaderidp type: RequestHeader requestHeader: challengeURL: "https://<namespace_route>/challenging-proxy/oauth/authorize?USD{query}" loginURL: "https://<namespace_route>/login-proxy/oauth/authorize?USD{query}" ca: name: ca-config-map clientCommonNames: - my-auth-proxy headers: - X-Remote-User
curl -L -k -H "X-Remote-User: joe" --cert /etc/pki/tls/certs/authproxy.pem https://<namespace_route>/oauth/token/request
curl -L -k -H "X-Remote-User: joe" https://<namespace_route>/oauth/token/request
curl -k -v -H 'X-Csrf-Token: 1' https://<namespace_route>/oauth/authorize?client_id=openshift-challenging-client&response_type=token
curl -k -v -H 'X-Csrf-Token: 1' <challengeURL_redirect + query>
kdestroy -c cache_name 1
oc login -u <username>
oc logout
kinit
oc login
https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>
https://oauth-openshift.apps.openshift-cluster.example.com/oauth2callback/github
oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret>
oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: githubidp 1 mappingMethod: claim 2 type: GitHub github: ca: 3 name: ca-config-map clientID: {...} 4 clientSecret: 5 name: github-secret hostname: ... 6 organizations: 7 - myorganization1 - myorganization2 teams: 8 - myorganization1/team-a - myorganization2/team-b
oc apply -f </path/to/CR>
oc login --token=<token>
oc whoami
oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret>
oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: gitlabidp 1 mappingMethod: claim 2 type: GitLab gitlab: clientID: {...} 3 clientSecret: 4 name: gitlab-secret url: https://gitlab.com 5 ca: 6 name: ca-config-map
oc apply -f </path/to/CR>
oc login -u <username>
oc whoami
oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret>
oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: googleidp 1 mappingMethod: claim 2 type: Google google: clientID: {...} 3 clientSecret: 4 name: google-secret hostedDomain: "example.com" 5
oc apply -f </path/to/CR>
oc login --token=<token>
oc whoami
oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config
apiVersion: v1 kind: Secret metadata: name: <secret_name> namespace: openshift-config type: Opaque data: clientSecret: <base64_encoded_client_secret>
oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config
oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
apiVersion: v1 kind: ConfigMap metadata: name: ca-config-map namespace: openshift-config data: ca.crt: | <CA_certificate_PEM>
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: oidcidp 1 mappingMethod: claim 2 type: OpenID openID: clientID: ... 3 clientSecret: 4 name: idp-secret claims: 5 preferredUsername: - preferred_username name: - name email: - email groups: - groups issuer: https://www.idp-issuer.com 6
apiVersion: config.openshift.io/v1 kind: OAuth metadata: name: cluster spec: identityProviders: - name: oidcidp mappingMethod: claim type: OpenID openID: clientID: clientSecret: name: idp-secret ca: 1 name: ca-config-map extraScopes: 2 - email - profile extraAuthorizeParameters: 3 include_granted_scopes: "true" claims: preferredUsername: 4 - preferred_username - email name: 5 - nickname - given_name - name email: 6 - custom_email_claim - email groups: 7 - groups issuer: https://www.idp-issuer.com
oc apply -f </path/to/CR>
oc login --token=<token>
oc login -u <identity_provider_username> --server=<api_server_url_and_port>
oc whoami