Authentication | Administrator Solutions | OpenShift Container Platform 3.7

Overview

OpenShift Container Platform supports many different authentication methods, as defined in Configuring Authentication:

Basic Authentication (Remote)
Request Header
Keystone
LDAP
GitHub

Basic Authentication (Remote)

Basic Authentication is a generic backend integration mechanism that allows users to log in to OpenShift Container Platform with credentials validated against a remote identity provider.

Basic Authentication must use an HTTPS connection to the remote server in order to prevent potential snooping of the user ID and password, and to prevent man-in-the-middle attacks.

With BasicAuthPasswordIdentityProvider 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 Auth header. This requires users to send their credentials to OpenShift Container Platform during login.

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.

Configuring Authentication on the Master

If you have:

Already completed the installation of Openshift, then copy the /etc/origin/master/master-config.yaml file into a new directory; for example:
```
$ mkdir basicauthconfig; cp master-config.yaml basicauthconfig
```

Not yet installed OpenShift Container Platform, then start the OpenShift Container Platform API server, specifying the hostname of the (future) OpenShift Container Platform master and a directory to store the configuration file created by the start command:

$ openshift start master --public-master=<apiserver> --write-config=<directory>

For example:

$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=basicauthconfig

If you are installing with Ansible, then you must add the identityProvider configuration to the Ansible playbook. If you use the following steps to modify your configuration manually after installing with Ansible, then you will lose any modifications whenever you re-run the install tool or upgrade.

edit the new master-config.yaml file’s identityProviders stanza.
Copy the example BasicAuthPasswordIdentityProvider configuration and paste it to replace the existing stanza.
Make the following modifications to the identityProviders stanza:
1. Set the provider name to something unique and relevant to your deployment. This name is prefixed to the returned user ID to form an identity name.
2. If required, set mappingMethod to control how mappings are established between the provider’s identities and user objects.
3. Specify the HTTPS url to use to connect to a server that accepts credentials in Basic authentication headers.
4. Optionally, set the ca to the certificate bundle to use in order to validate server certificates for the configured URL, or leave it empty to use the system-trusted roots.
5. Optionally, remove or set the certFile to the client certificate to present when making requests to the configured URL.
6. If certFile is specified, then you must set the keyFile to the key for the client certificate.
Save your changes and close the file.
Start the OpenShift Container Platform API server, specifying the configuration file you just modified:
```
$ openshift start master --config=<path/to/modified/config>/master-config.yaml
```

Once configured, any user logging in to the OpenShift Container Platform web console will be prompted to log in using their Basic authentication credentials.

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.

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 may 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"}

Verifying Users

Once one or more users have logged in, you can run oc get users to view a list of users and verify that users were created successfully.

From here, you might want to learn how to control user roles.

Request Header Authentication

Configuring Request Header authentication allows users to log in to OpenShift Container Platform using request header values, such as X-Remote-User. It is typically used in combination with an authenticating proxy, which authenticates the user and then provides OpenShift Container Platform with the user’s identity via a request header value. This is similar to how the remote user plug-in in OpenShift enterprise 2 allowed administrators to provide Kerberos, LDAP, and many other forms of enterprise authentication. The benefit of this configuration is that user credentials can be handled by the proxy and never seen by OpenShift.

The proxy must be able to make network requests to the OpenShift Container Platform server. Unauthenticated login attempts are redirected to a configured proxy URL. The proxy can authenticate browser clients regardless of how it is configured, but it must (currently) use either Basic Auth or Kerberos in order to work with the oc CLI tooling.

For users to authenticate using this identity provider, they must access https://<master>/oauth/authorize via an authenticating proxy. You can configure the OAuth server to redirect unauthenticated requests to the proxy.

Configuring Authentication on the Master

If you have:

Already completed the installation of Openshift, then copy the /etc/origin/master/master-config.yaml file into a new directory; for example:
```
$ mkdir reqheadauthconfig; cp master-config.yaml reqheadauthconfig
```

$ openshift start master --public-master=<apiserver> --write-config=<directory>

For example:

$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=reqheadauthconfig

edit the new master-config.yaml file’s identityProviders stanza.
View the example RequestHeaderIdentityProvider configuration and use it as a guide to replace the existing stanza.

Modify the identityProviders stanza based on which headers you plan to pass in.

Set the provider name to something unique and relevant to your deployment. This name is prefixed to the returned user ID to form an identity name.
If required, set mappingMethod to control how mappings are established between the provider’s identities and user objects.
Set the challenge parameter to true to redirect unauthenticated requests from clients expecting WWW-Authenticate challenges.
Set the provider.challengeURL parameter to the proxy URL to which to send clients expecting WWW-Authenticate challenges, like the oc CLI client. This parameter can include the ${url} and ${query} tokens in the query portion of the URL.
Set the login parameter to true to redirect unauthenticated requests from clients expecting login flows.
Set the provider.loginURL parameter to the proxy URL to which to send clients expecting login flows, like web browser clients. This parameter can include the ${url} and ${query} tokens in the query portion of the URL.

Set the clientCA parameter to the certificate bundle to use to check incoming requests for a valid client certificate before the request’s headers are checked for a user name.

If you expect unauthenticated requests to reach the OAuth server, a clientCA parameter (and optionally, clientCommonNames) should be set for this identity provider. Otherwise, any direct request to the OAuth server can impersonate any identity from this provider, merely by setting a request header.

Optionally, set the clientCommonNames parameter to 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 user names. If empty, then any Common Name is allowed. This must be used in combination with clientCA.
Set the headers parameter to the header names to check, in order, for the user identity. The first header containing a value is used as the identity. This parameter is required and is case-insensitive.
Optionally, set the emailHeaders parameter to the header names to check, in order, for an email address. The first header containing a value is used as the email address. This parameter is case-insensitive.
Optionally, set the nameHeaders parameter to the header names to check, in order, for a display name. The first header containing a value is used as the display name. This parameter is case-insensitive.
Optionally, set the preferredUsernameHeaders parameter to the 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. This parameter is case-insensitive.

Save your changes and close the file.
Start the OpenShift Container Platform API server, specifying the configuration file you just modified:
```
$ openshift start master --config=<path/to/modified/config>/master-config.yaml
```

Once configured, any user logging in to the OpenShift Container Platform web console will be redirected to the authenticating proxy, which will authenticate the user.

Creating Users with Request Header Authentication

You do not create users in OpenShift Container Platform when integrating with an external authentication provider, such as the system that the proxy server is using as an authentication server. That server is the system of record, meaning that users are defined there, and any user with a valid user name for the configured authentication server can log in.

To add a user to OpenShift Container Platform, the user must exist on the system the proxy is using as an authentication server, and if required you must add the users to that system.

Verifying Users

Once one or more users have logged in, you can run oc get users to view a list of users and verify that users were created successfully.

From here, you might want to examine configuring LDAP failover for an example of Request Header authentication in use with Apache. You can also learn how to control user roles.

Keystone Authentication

Keystone is an OpenStack project that provides identity, token, catalog, and policy services. You can 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. Once configured, this configuration allows users to log in to OpenShift Container Platform with their Keystone credentials.

Configuring Authentication on the Master

If you have:

Already completed the installation of Openshift, then copy the /etc/origin/master/master-config.yaml file into a new directory; for example:
```
$ cd /etc/origin/master
$ mkdir keystoneconfig; cp master-config.yaml keystoneconfig
```

$ openshift start master --public-master=<apiserver> --write-config=<directory>

For example:

$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=keystoneconfig

edit the new keystoneconfig/master-config.yaml file’s identityProviders stanza.
Copy the example KeystonePasswordIdentityProvider configuration and paste it to replace the existing stanza.
Make the following modifications to the identityProviders stanza:
1. Change the provider name ("my_keystone_provider") to match your Keystone server. This name is prefixed to provider user names to form an identity name.
2. If required, change mappingMethod to control how mappings are established between the provider’s identities and user objects.
3. Change the domainName to the domain name of your OpenStack Keystone server. In Keystone, user names are domain-specific. Only a single domain is supported.
4. Specify the url to use to connect to your OpenStack Keystone server.
5. Optionally, change the ca to the certificate bundle to use in order to validate server certificates for the configured URL.
6. Optionally, change the certFile to the client certificate to present when making requests to the configured URL.
7. If certFile is specified, then you must change the keyFile to the key for the client certificate.
Save your changes and close the file.
Start the OpenShift Container Platform API server, specifying the configuration file you just modified:
```
$ openshift start master --config=<path/to/modified/config>/master-config.yaml
```

Once configured, any user logging in to the OpenShift Container Platform web console will be prompted to log in using their Keystone credentials.

Creating Users with Keystone Authentication

You do not create users in OpenShift Container Platform when integrating with an external authentication provider, such as, in this case, Keystone. Keystone is the system of record, meaning that users are defined in a Keystone database, and any user with a valid Keystone user name for the configured authentication server can log in.

To add a user to OpenShift Container Platform, the user must exist in the Keystone database, and if required you must create a new Keystone account for the user.

Verifying Users

Once one or more users have logged in, you can run oc get users to view a list of users and verify that users were created successfully:

example 1. Output of oc get users command

$ oc get users
NAMe         UID                                    FULL NAMe   IDeNTITIeS
bobsmith     a0c1d95c-1cb5-11e6-a04a-002186a28631   Bob Smith   keystone:bobsmith (1)

1	Identities in OpenShift Container Platform are comprised of the identity provider name prefixed to the Keystone user name.

From here, you might want to learn how to control user roles.

LDAP Authentication

LDAP uses bind operations to authenticate applications, and you can integrate your OpenShift Container Platform cluster to use LDAPv3 authentication. Configuring LDAP authentication allows users to log in to OpenShift Container Platform with their LDAP credentials.

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.

The basic authentication configuration covered by this topic is not enough to create a secure LDAP authentication solution for OpenShift Container Platform. It has a single point of failure, meaning that if the single LDAP authentication server became unavailable then all OpenShift Container Platform operations requiring authentication would also be unavailable.

Additionally, this basic configuration has no access control of its own; all LDAP users matching the configured filter are able to log into OpenShift Container Platform.

With the SSSD failover setup, FreeIPA and Active Directory can also set rules to specifically restrict which users can and cannot access OpenShift Container Platform.

The following advanced topic begin where this basic LDAP authentication topic ends and describe configuring LDAP failover.

Configuring Authentication on the Master

If you have:

Already completed the installation of Openshift, then copy the /etc/origin/master/master-config.yaml file into a new directory; for example:
```
$ cd /etc/origin/master
$ mkdir ldapconfig; cp master-config.yaml ldapconfig
```

$ openshift start master --public-master=<apiserver> --write-config=<directory>

For example:

$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=ldapconfig

edit the new master-config.yaml file’s identityProviders stanza.
Copy the example LDAPPasswordIdentityProvider configuration and paste it to replace the existing stanza.
Make the following modifications to the identityProviders stanza:
1. Change the provider name ("my_ldap_provider") to something unique and relevant to your deployment. This name is prefixed to the returned user name to form an identity name.
2. If required, change mappingMethod to control how mappings are established between the provider’s identities and user objects.
3. Change id to the attribute to use as the identity, which must be unique and immutable within the identity provider. This option can accept multiple attributes. If more than one is specified, they will be checked in order and the first non-empty attribute will be used. At least one attribute is required. If none of the listed attribute have a value, then authentication fails.
4. Change email to the attribute to use as the email address. This option can accept multiple attributes. If more than one is specified, they will be checked in order and the first non-empty attribute will be used.
5. Change name to the attribute to use as the display name. This option can accept multiple attributes. If more than one is specified, they will be checked in order and the first non-empty attribute will be used.
6. Optionally, change preferredUsername to the attribute to use as the preferred OpenShift Container Platform user name when provisioning a user for this identity. If unspecified, the id attribute is used as the preferred user name. This option can accept multiple attributes. If more than one is specified, they will be checked in order and the first non-empty attribute will be used.
  
  The attribute you select as the preferredUsername should still be unique, even within the identity provider. The preferredUsername attribute is only used when provisioning the user for the initial login. Afterward, the existing OpenShift Container Platform user is looked up by their identity provider ID, in case the preferredUsername attribute changes.
  
  Using preferredUsername is helpful when the immutable id attribute is not a human-recognizable value, and there is another attribute with a value that is more recognizable to the user. For example, if the id is something like "e43adf8cc243", you could set preferredUsername to login, which could have potentially muteable values, such as "bobsmith".
7. Change the ca to the certificate bundle to use in order to validate server certificates for the configured URL. If empty, system trusted roots are used. This setting only applies if insecure: false. If the LDAP server requires a different certificate chain, this attribute should contain the filesystem path of that certificate or certificate bundle.
8. If required, modify the insecure parameter. The default is false, and this must be false when using ldaps:// URLs. When false, ldaps:// URLs connect using TLS, and ldap:// URLs are upgraded to TLS. When true, no TLS connection is made to the server, however, setting this to true creates an invalid configuration for LDAP.
9. Define an RFC 2255 URL that specifies the LDAP host and search parameters to use.
Save your changes and close the file.
Start the OpenShift Container Platform API server, specifying the configuration file you just modified:
```
$ openshift start master --master-config=<path/to/modified/config>/master-config.yaml
```

Once configured, any user logging in to the OpenShift Container Platform web console will be prompted to log in using their LDAP credentials.

Creating Users with LDAP Authentication

You do not create users in OpenShift Container Platform when integrating with an external authentication provider, such as, in this case, LDAP. LDAP is the system of record, meaning that users are defined in LDAP, and any user with a valid LDAP ID for the configured authentication server can log in.

To add a user to OpenShift Container Platform, the user must exist in the LDAP system, and if required you must create a new LDAP account for the user.

Verifying Users

Once one or more users have logged in, you can run oc get users to view a list of users and verify that users were created successfully:

example 2. Output of oc get users command

$ oc get users
NAMe       UID                                    FULL NAMe   IDeNTITIeS
bobsmith   166a2367-33fc-11e6-bb22-4ccc6a0ad630   Bob Smith   ldap_provider:uid=bsmith,ou=users,dc=example,dc=com (1)

1	Identities in OpenShift Container Platform are comprised of the identity provider name prefixed to the LDAP distinguished name (DN).

From here, you might want to learn how to control user roles.

GitHub Authentication

GitHub uses OAuth, and you can integrate your OpenShift Container Platform cluster to use that OAuth authentication. OAuth basically facilitates a token exchange flow.

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.

Registering the Application on GitHub

On GitHub, click Settings → OAuth applications → Developer applications → Register an application to navigate to the page for a new OAuth application.
Type an application name. For example: My OpenShift Install
Type a homepage URL. For example: https://myapiserver.com:8443
Optionally, type an application description.
Type the authorization callback URL, where the end of the URL contains the identity provider name (defined in the identityProviders stanza of the master configuration file, which you configure in the next section of this topic):
```
<apiserver>/oauth2callback/<identityProviderName>
```
For example:
```
https://myapiserver.com:8443/oauth2callback/github/
```
Click Register application. GitHub provides a Client ID and a Client Secret. Keep this window open so you can copy these values and paste them into the master configuration file.

Configuring Authentication on the Master

If you have:

Already completed the installation of Openshift, then copy the /etc/origin/master/master-config.yaml file into a new directory; for example:
```
$ cd /etc/origin/master
$ mkdir githubconfig; cp master-config.yaml githubconfig
```

$ openshift start master --public-master=<apiserver> --write-config=<directory>

For example:

$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=githubconfig

Using openshift start master on its own would auto-detect host names, but GitHub must be able to redirect to the exact host name that you specified when registering the application. For this reason, you cannot auto-detect the ID because it might redirect to the wrong address. Instead, you must specify the hostname that web browsers use to interact with your OpenShift Container Platform cluster.

edit the new master-config.yaml file’s identityProviders stanza.
Copy the example GitHubIdentityProvider configuration and paste it to replace the existing stanza.
Make the following modifications to the identityProviders stanza:
1. Change the provider name to match the callback URL you configured on GitHub.
  
  For example, if you defined the callback URL as https://myapiserver.com:8443/oauth2callback/github/ then the name must be github.
2. Change clientID to the Client ID from GitHub that you registered previously.
3. Change clientSecret to the Client Secret from GitHub that you registered previously.
4. Change organizations or teams to include a list of one or more GitHub organizations or teams to which a user must have membership in order to authenticate. If specified, only GitHub users that are members of at least one of the listed organizations or teams will be allowed to log in. If this is not specified, then any person with a valid GitHub account can log in.
Save your changes and close the file.
Start the OpenShift Container Platform API server, specifying the configuration file you just modified:
```
$ openshift start master --config=<path/to/modified/config>/master-config.yaml
```

Once configured, any user logging in to the OpenShift Container Platform web console will be prompted to log in using their GitHub credentials. On their first login, the user must click authorize application to permit GitHub to use their user name, password, and organization membership with OpenShift Container Platform. The user is then redirected back to the web console.

Creating Users with GitHub Authentication

You do not create users in OpenShift Container Platform when integrating with an external authentication provider, such as, in this case, GitHub. GitHub is the system of record, meaning that users are defined by GitHub, and any user belonging to a specified organization can log in.

To add a user to OpenShift Container Platform, you must add that user to an approved organization on GitHub, and if required create a new GitHub account for the user.

Verifying Users

Once one or more users have logged in, you can run oc get users to view a list of users and verify that users were created successfully:

example 3. Output of oc get users command

$ oc get users
NAMe         UID                                    FULL NAMe   IDeNTITIeS
bobsmith     433b5641-066f-11e6-a6d8-acfc32c1ca87   Bob Smith   github:873654 (1)

Identities in OpenShift Container Platform are comprised of the identity provider name and GitHub’s internal numeric user ID. This way, if a user changes their GitHub user name or e-mail they can still log in to OpenShift Container Platform instead of relying on the credentials attached to the GitHub account. This creates a stable login.

From here, you might want to learn how to control user roles.