Configuring Authentication | Installation and Configuration

Overview
Identity Providers
Token Options
Grant Options
Session Options

Overview

The OpenShift master includes a built-in OAuth server. Developers and administrators obtain OAuth access tokens to authenticate themselves to the API.

As an administrator, you can configure OAuth using the master configuration file to specify an identity provider. If you installed OpenShift Enterprise using the Quick Installation or Advanced Installation method, the Deny All identity provider is used by default, which denies access for all user names and passwords. To allow access, you must choose a different identity provider and configure the master configuration file appropriately (located at /etc/origin/master/master-config.yaml by default).

When running a master without a configuration file, the Allow All identity provider is used by default, which allows any non-empty user name and password to log in. This is useful for testing purposes. To use other identity providers, or to modify any token, grant, or session options, you must run the master from a configuration file.

Roles need to be assigned to administer the setup with an external user.

Identity Providers

You can configure the master host for authentication using your desired identity provider by modifying the master configuration file. The following sections detail the identity providers supported by OpenShift.

There are four parameters common to all identity providers:

Parameter Description

Parameter	Description
`name`	The provider name is prefixed to provider user names to form an identity name.
`challenge`	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header. Not supported by all identity providers. To prevent cross-site request forgery (CSRF) attacks against browser clients Basic authentication challenges are only sent if a `X-CSRF-Token` header is present on the request. Clients that expect to receive Basic `WWW-Authenticate` challenges should set this header to a non-empty value.
`login`	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider. Not supported by all identity providers.
`mappingMethod`	Defines how new identities are mapped to users when they login. See Mapping Identities to Users for more information.

name

The provider name is prefixed to provider user names to form an identity name.

challenge

When true, unauthenticated token requests from non-web clients (like the CLI) are sent a WWW-Authenticate challenge header. Not supported by all identity providers.

To prevent cross-site request forgery (CSRF) attacks against browser clients Basic authentication challenges are only sent if a X-CSRF-Token header is present on the request. Clients that expect to receive Basic WWW-Authenticate challenges should set this header to a non-empty value.

login

When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider. Not supported by all identity providers.

mappingMethod

Defines how new identities are mapped to users when they login. See Mapping Identities to Users for more information.

When adding or changing identity providers, you can map identities from the new provider to existing users by setting the mappingMethod parameter to add.

Mapping Identities to Users

Setting the mappingMethod parameter in a master configuration file determines how identities are mapped to users:

...
oauthConfig:
  identityProviders:
  - name: htpasswd_auth
    challenge: true
    login: false
    mappingMethod: "claim"
...

When set to the default claim value, OAuth will fail if the identity is mapped to a previously-existing user name. The following table outlines the use cases for the available mappingMethod parameter values:

Parameter Description

Parameter	Description
`claim`	The default value. Provisions a user with the identity’s preferred user name. Fails if a user with that user name is already mapped to another identity.
`lookup`	Looks up an existing identity, user identity mapping, and user, but does not automatically provision users or identities. This allows cluster administrators to set up identities and users manually, or using an external process.
`generate`	Provisions a user with the identity’s preferred user name. If a user with the preferred user name is already mapped to an existing identity, a unique user name is generated. For example, myuser2. This method should not be used in combination with external processes that require exact matches between OpenShift user names and identity provider user names, such as LDAP group sync.
`add`	Provisions a user with the identity’s preferred user name. If a user with that user name already exists, the identity is mapped to the existing user, adding to any existing identity mappings for the user. Required when multiple identity providers are configured that identify the same set of users and map to the same user names.

claim

The default value. Provisions a user with the identity’s preferred user name. Fails if a user with that user name is already mapped to another identity.

lookup

Looks up an existing identity, user identity mapping, and user, but does not automatically provision users or identities. This allows cluster administrators to set up identities and users manually, or using an external process.

generate

Provisions a user with the identity’s preferred user name. If a user with the preferred user name is already mapped to an existing identity, a unique user name is generated. For example, myuser2. This method should not be used in combination with external processes that require exact matches between OpenShift user names and identity provider user names, such as LDAP group sync.

add

Provisions a user with the identity’s preferred user name. If a user with that user name already exists, the identity is mapped to the existing user, adding to any existing identity mappings for the user. Required when multiple identity providers are configured that identify the same set of users and map to the same user names.

Allow All

Set AllowAllPasswordIdentityProvider in the identityProviders stanza to allow any non-empty user name and password to log in. This is the default identity provider when running OpenShift without a master configuration file.

Example 1. Master Configuration Using AllowAllPasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_allow_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: AllowAllPasswordIdentityProvider

1	This provider name is prefixed to provider user names to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.

Deny All

Set DenyAllPasswordIdentityProvider in the identityProviders stanza to deny access for all user names and passwords.

Example 2. Master Configuration Using DenyAllPasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_deny_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: DenyAllPasswordIdentityProvider

1	This provider name is prefixed to provider user names to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.

HTPasswd

Set HTPasswdPasswordIdentityProvider in the identityProviders stanza to validate user names and passwords against a flat file generated using htpasswd.

The htpasswd utility is in the httpd-tools package:

# yum install httpd-tools

Only MD5, bcrypt, and SHA encryption types are supported. MD5 encryption is recommended, and is the default for htpasswd. Plaintext and crypt hashes are not currently supported.

The flat file is re-read if its modification time changes, without requiring a server restart.

To create the file, run:

$ htpasswd -c </path/to/users.htpasswd> <user_name>

To add or update a login to the file, run:

$ htpasswd </path/to/users.htpasswd> <user_name>

To remove a login from the file, run:

$ htpasswd -D </path/to/users.htpasswd> <user_name>

Example 3. Master Configuration Using HTPasswdPasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_htpasswd_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: HTPasswdPasswordIdentityProvider
      file: /path/to/users.htpasswd (5)

1	This provider name is prefixed to provider user names to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	File generated using `htpasswd`.

Keystone

Set KeystonePasswordIdentityProvider in the identityProviders stanza to validate user names and passwords against an OpenStack Keystone v3 server. This enables shared authentication with an OpenStack server configured to store users in an internal Keystone database.

Example 4. Master Configuration Using KeystonePasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_keystone_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: KeystonePasswordIdentityProvider
      domainName: default (5)
      ca: ca.pem (6)
      certFile: keystone.pem (7)
      keyFile: keystonekey.pem (8)

1	This provider name is prefixed to provider user names to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported.
6	Optional: Certificate bundle to use to validate server certificates for the configured URL.
7	Optional: Client certificate to present when making requests to the configured URL.
8	Key for the client certificate. Required if `certFile` is specified.

LDAP Authentication

Set LDAPPasswordIdentityProvider in the identityProviders stanza to validate user names and passwords against an LDAPv3 server, using simple bind 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. Here 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:

ldap://host:port/basedn?attribute?scope?filter

For the above example:

URL Component Description

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 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=*)`

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 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:

(&(<filter>)(<attribute>=<username>))

For example, consider a URL of:

ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true)

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.

Example 5. Master Configuration Using LDAPPasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: "my_ldap_provider" (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: LDAPPasswordIdentityProvider
      attributes:
        id: (5)
        - dn
        email: (6)
        - mail
        name: (7)
        - cn
        preferredUsername: (8)
        - uid
      bindDN: "" (9)
      bindPassword: "" (10)
      ca: my-ldap-ca-bundle.crt (11)
      insecure: false (12)
      url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" (13)

1	This provider name is prefixed to the returned user ID to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	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.
6	List of attributes to use as the email address. First non-empty attribute is used.
7	List of attributes to use as the display name. First non-empty attribute is used.
8	List of attributes to use as the preferred user name when provisioning a user for this identity. First non-empty attribute is used.
9	Optional DN to use to bind during the search phase.
10	Optional password to use to bind during the search phase.
11	Certificate bundle to use to validate server certificates for the configured URL. If empty, system trusted roots are used. Only applies if insecure: false.
12	When true, no TLS connection is made to the server. When false, `ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to TLS.
13	An RFC 2255 URL which specifies the LDAP host and search parameters to use, as described above.

Basic Authentication (Remote)

Set BasicAuthPasswordIdentityProvider in the identityProviders stanza to validate user names and passwords against a remote server using a server-to-server Basic authentication request. 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 may 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 user for the authenticated identity. For example:
```
{"sub":"014fbff9a07c", "preferred_username":"bob", ...}
```

Example 6. Master Configuration Using BasicAuthPasswordIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_remote_basic_auth_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: BasicAuthPasswordIdentityProvider
      url: https://www.example.com/remote-idp (5)
      ca: /path/to/ca.file (6)
      certFile: /path/to/client.crt (7)
      keyFile: /path/to/client.key (8)

1	This provider name is prefixed to the returned user ID to form an identity name.
2	When true, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to a login page backed by this provider.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	URL accepting credentials in Basic authentication headers.
6	Optional: Certificate bundle to use to validate server certificates for the configured URL.
7	Optional: Client certificate to present when making requests to the configured URL.
8	Key for the client certificate. Required if `certFile` is specified.

Request Header

Set RequestHeaderIdentityProvider in the identityProviders stanza 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. 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.

For users to authenticate using this identity provider, they must access <master>/oauth/authorize via an authenticating proxy. You can either proxy the entire master API server so that all access goes through the proxy, or you can configure the OAuth server to redirect unauthenticated requests to the proxy.

To redirect unauthenticated requests from clients expecting login flows:

Set the login parameter to true.
Set the provider.loginURL parameter to the proxy URL to send those clients to.

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

Set the challenge parameter to true.
Set the provider.challengeURL parameter to the proxy URL to send those clients to.

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

${url} is replaced with the current URL, escaped to be safe in a query parameter.

For example: https://www.example.com/sso-login?then=${url}
${query} is replaced with the current query string, unescaped.

For example: https://www.example.com/auth-proxy/oauth/authorize?${query}

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

Example 7. Master Configuration Using RequestHeaderIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_request_header_provider (1)
    challenge: true (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: RequestHeaderIdentityProvider
      challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" (5)
      loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" (6)
      clientCA: /path/to/client-ca.file (7)
      headers: (8)
      - X-Remote-User
      - SSO-User

1	This provider name is prefixed to the user name in the request header to form an identity name.
2	RequestHeaderIdentityProvider can only respond to clients that request `WWW-Authenticate` challenges by redirecting to a configured `challengeURL`. The configured URL should respond with a `WWW-Authenticate` challenge.
3	RequestHeaderIdentityProvider can only respond to clients requesting a login flow by redirecting to a configured `loginURL`. The configured URL should respond with a login flow.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	Optional: URL to redirect unauthenticated /oauth/authorize requests to, for clients which expect interactive logins. ${url} is replaced with the current URL, escaped to be safe in a query parameter. ${query} is replaced with the current query string.
6	Optional: URL to redirect unauthenticated /oauth/authorize requests to, for clients which expect `WWW-Authenticate` challenges. ${url} is replaced with the current URL, escaped to be safe in a query parameter. ${query} is replaced with the current query string.
7	Optional: PEM-encoded certificate bundle. If set, a valid client certificate must be presented and validated against the certificate authorities in the specified file before the request headers are checked for user names.
8	Header names to check, in order, for user names. The first header containing a value is used as the user name. Required, case-insensitive.

Example 8. Apache Authentication Using RequestHeaderIdentityProvider

This example configures an authentication proxy on the same host as the master. Having the proxy and master on the same host is merely a convenience and may not be suitable for your environment. For example, if you were already running a router on the master, port 443 would not be available.

It is also important to note that while this reference configuration uses Apache’s mod_auth_form, it is by no means required and 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 request using the challenge flow.
Only the /oauth/authorize endpoint should be proxied, and redirects should not be rewritten to allow the backend server to send the client to the correct location.

Installing the Prerequisites

The mod_auth_form module is shipped as part of the mod_session package that is found in the Optional channel:

# yum install -y httpd mod_ssl mod_session apr-util-openssl

Generate a CA for validating requests that submit the trusted header. This CA should be used as the file name for clientCA in the master’s identity provider configuration.

# oadm ca create-signer-cert \
  --cert='/etc/origin/master/proxyca.crt' \
  --key='/etc/origin/master/proxyca.key' \
  --name='openshift-proxy-signer@1432232228' \
  --serial='/etc/origin/master/proxyca.serial.txt'

Generate a client certificate for the proxy. This can be done using any x509 certificate tooling. For convenience, the oadm CLI can be used:

# oadm create-api-client-config \
  --certificate-authority='/etc/origin/master/proxyca.crt' \
  --client-dir='/etc/origin/master/proxy' \
  --signer-cert='/etc/origin/master/proxyca.crt' \
  --signer-key='/etc/origin/master/proxyca.key' \
  --signer-serial='/etc/origin/master/proxyca.serial.txt' \
  --user='system:proxy' (1)

# pushd /etc/origin/master
# cp master.server.crt /etc/pki/tls/certs/localhost.crt (2)
# cp master.server.key /etc/pki/tls/private/localhost.key
# cp ca.crt /etc/pki/CA/certs/ca.crt
# cat proxy/system\:proxy.crt \
  proxy/system\:proxy.key > \
  /etc/pki/tls/certs/authproxy.pem
# popd

1 The user name can be anything, however it is useful to give it a descriptive name as it will appear in logs.

2 When running the authentication proxy on a different host name than the master, it is important to generate a certificate that matches the host name instead of using the default master certificate as shown above. The value for masterPublicURL in the /etc/origin/master/master-config.yaml file must be included in the X509v3 Subject Alternative Name in the certificate that is specified for SSLCertificateFile. If a new certificate needs to be created, the oadm ca create-server-cert command can be used.

Configuring Apache

Unlike OpenShift Enterprise 2, this proxy does not need to reside on the same host as the master. It uses a client certificate to connect to the master, which is configured to trust the X-Remote-User header.

Configure Apache per the following:

LoadModule auth_form_module modules/mod_auth_form.so
LoadModule session_module modules/mod_session.so
LoadModule request_module modules/mod_request.so

# Nothing needs to be served over HTTP.  This virtual host simply redirects to
# HTTPS.
<VirtualHost *:80>
  DocumentRoot /var/www/html
  RewriteEngine              On
  RewriteRule     ^(.*)$     https://%{HTTP_HOST}$1 [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's critical to enforce client certificates on the Master.  Otherwise
  # requests could spoof the X-Remote-User header by accessing the Master's
  # /oauth/authorize endpoint directly.
  SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem

  # Send all requests to the console
  RewriteEngine              On
  RewriteRule     ^/console(.*)$     https://%{HTTP_HOST}:8443/console$1 [R,L]

  # In order to using the challenging-proxy an X-Csrf-Token must be present.
  RewriteCond %{REQUEST_URI} ^/challenging-proxy
  RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC]
  RewriteRule ^.* - [F,L]

  <Location /challenging-proxy/oauth/authorize>
    # Insert your backend server name/ip here.
    ProxyPass https://[MASTER]:8443/oauth/authorize
    AuthType basic
  </Location>

  <Location /login-proxy/oauth/authorize>
    # Insert your backend server name/ip here.
    ProxyPass https://[MASTER]:8443/oauth/authorize

    # mod_auth_form providers are implemented by mod_authn_dbm, mod_authn_file,
    # mod_authn_dbd, mod_authnz_ldap and mod_authn_socache.
    AuthFormProvider file
    AuthType form
    AuthName openshift
    ErrorDocument 401 /login.html
  </Location>

  <ProxyMatch /oauth/authorize>
    AuthUserFile /etc/origin/master/htpasswd
    AuthName openshift
    Require valid-user
    RequestHeader set X-Remote-User %{REMOTE_USER}s

    # For ldap:
    # AuthBasicProvider ldap
    # AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?sub?(objectClass=*)"

    # It's possible to remove the mod_auth_form usage and replace it with
    # something like mod_auth_kerb, mod_auth_gsspai or even mod_auth_mellon.
    # The former would be able to support both the login and challenge flows
    # from the Master.  Mellon would likely only support the login flow.

    # For Kerberos
    # yum install mod_auth_gssapi
    # AuthType GSSAPI
    # GssapiCredStore keytab:/etc/httpd.keytab
  </ProxyMatch>

</VirtualHost>

RequestHeader unset X-Remote-User

Additional mod_auth_form Requirements

A sample login page is available from the openshift_extras repository. This file should be placed in the DocumentRoot location (/var/www/html by default).

Creating Users

At this point, you can create the users in the system Apache is using to store accounts information. In this example, file-backed authentication is used:

# yum -y install httpd-tools
# touch /etc/origin/master/htpasswd
# htpasswd /etc/origin/master/htpasswd <user_name>

Configuring the Master

The identityProviders stanza in the /etc/origin/master/master-config.yaml file must be updated as well:

  identityProviders:
  - name: requestheader
    challenge: true
    login: true
    provider:
      apiVersion: v1
      kind: RequestHeaderIdentityProvider
      challengeURL: "https://[MASTER]/challenging-proxy/oauth/authorize?${query}"
      loginURL: "https://[MASTER]/login-proxy/oauth/authorize?${query}"
      clientCA: /etc/origin/master/proxyca.crt
      headers:
      - X-Remote-User

Restarting Services

Finally, restart the following services:

# systemctl restart httpd
# systemctl restart atomic-openshift-master

Verifying the Configuration

Test by bypassing the proxy. You should be able to request a token if you supply the correct client certificate and header:

# curl -L -k -H "X-Remote-User: joe" \
   --cert /etc/pki/tls/certs/authproxy.pem \
   https://[MASTER]:8443/oauth/token/request

If you do not supply the client certificate, the request should be denied:

# curl -L -k -H "X-Remote-User: joe" \
   https://[MASTER]:8443/oauth/token/request

This should show a redirect to the configured challengeURL (with additional query parameters):

# curl -k -v -H 'X-Csrf-Token: 1' \
   '<masterPublicURL>/oauth/authorize?client_id=openshift-challenging-client&response_type=token'

This should show a 401 response with a WWW-Authenticate basic challenge:

#  curl -k -v -H 'X-Csrf-Token: 1' \
    '<redirected challengeURL from step 3 +query>'

This should show a redirect with an access token:

#  curl -k -v -u <your_user>:<your_password> \
    -H 'X-Csrf-Token: 1' '<redirected_challengeURL_from_step_3 +query>'

GitHub

Set GitHubIdentityProvider in the identityProviders stanza to use GitHub as an identity provider, using the OAuth integration.

Using GitHub as an identity provider requires users to get a token using <master>/oauth/token/request to use with command-line tools.

Example 9. Master Configuration Using GitHubIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: github (1)
    challenge: false (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: GitHubIdentityProvider
      clientID: ... (5)
      clientSecret: ... (6)

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	GitHubIdentityProvider cannot be used to send `WWW-Authenticate` challenges.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to GitHub to log in.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	The client ID of a registered GitHub OAuth application. The application must be configured with a callback URL of `<master>/oauth2callback/<identityProviderName>`.
6	The client secret issued by GitHub.

Google

Set GoogleIdentityProvider in the identityProviders stanza to use Google as an identity provider, using Google’s OpenID Connect integration.

Using Google as an identity provider requires users to get a token using <master>/oauth/token/request to use with command-line tools.

Example 10. Master Configuration Using GoogleIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: google (1)
    challenge: false (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: GoogleIdentityProvider
      clientID: ... (5)
      clientSecret: ... (6)
      hostedDomain: "" (7)

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	GoogleIdentityProvider cannot be used to send `WWW-Authenticate` challenges.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to Google to log in.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	The client ID of a registered Google project. The project must be configured with a redirect URI of `<master>/oauth2callback/<identityProviderName>`.
6	The client secret issued by Google.
7	Optional hosted domain to restrict sign-in accounts to. If empty, any Google account is allowed to authenticate.

OpenID Connect

Set OpenIDIdentityProvider in the identityProviders stanza to integrate with an OpenID Connect identity provider using an Authorization Code Flow.

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 standard claims are:

`sub`	The user identity.
`preferred_username`	The preferred user name when provisioning a user.
`email`	Email address.
`name`	Display name.

Using an OpenID Connect identity provider requires users to get a token using <master>/oauth/token/request to use with command-line tools.

Example 11. Standard Master Configuration Using OpenIDIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_openid_connect (1)
    challenge: false (2)
    login: true (3)
    mappingMethod: claim (4)
    provider:
      apiVersion: v1
      kind: OpenIDIdentityProvider
      clientID: ... (5)
      clientSecret: ... (6)
      claims:
        id:
        - sub (7)
        preferredUsername:
        - preferred_username
        name:
        - name
        email:
        - email
      urls:
        authorize: https://myidp.example.com/oauth2/authorize (8)
        token: https://myidp.example.com/oauth2/token (9)

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	OpenIDIdentityProvider cannot be used to send `WWW-Authenticate` challenges.
3	When true, unauthenticated token requests from web clients (like the web console) are redirected to the authorize URL to log in.
4	Controls how mappings are established between this provider’s identities and user objects, as described above.
5	The client ID of a client registered with the OpenID provider. The client must be allowed to redirect to `<master>/oauth2callback/<identityProviderName>`.
6	The client secret.
7	Use the value of the `sub` claim in the returned `id_token` as the user’s identity.
8	Authorization Endpoint described in the OpenID spec. Must use `https`.
9	Token Endpoint described in the OpenID spec. Must use `https`.

A custom certificate bundle, extra scopes, extra authorization request parameters, and userInfo URL can also be specified:

Example 12. Full Master Configuration Using OpenIDIdentityProvider

oauthConfig:
  ...
  identityProviders:
  - name: my_openid_connect
    challenge: false
    login: true
    mappingMethod: claim
    provider:
      apiVersion: v1
      kind: OpenIDIdentityProvider
      clientID: ...
      clientSecret: ...
      ca: my-openid-ca-bundle.crt (1)
      extraScopes: (2)
      - email
      - profile
      extraAuthorizeParameters: (3)
        include_granted_scopes: "true"
      claims:
        id: (4)
        - custom_id_claim
        - sub
        preferredUsername: (5)
        - preferred_username
        - email
        name: (6)
        - nickname
        - given_name
        - name
        email: (7)
        - custom_email_claim
        - email
      urls:
        authorize: https://myidp.example.com/oauth2/authorize
        token: https://myidp.example.com/oauth2/token
        userInfo: https://myidp.example.com/oauth2/userinfo (8)

1	Certificate bundle to use to validate server certificates for the configured URLs. If empty, system trusted roots are used.
2	Optional list of scopes to request, in addition to the openid scope, during the authorization token request.
3	Optional map of extra parameters to add to the authorization token request.
4	List of claims to use as the identity. First non-empty claim is used. At least one claim is required. If none of the listed claims have a value, authentication fails.
5	List of claims to use as the preferred user name when provisioning a user for this identity. First non-empty claim is used.
6	List of claims to use as the display name. First non-empty claim is used.
7	List of claims to use as the email address. First non-empty claim is used.
8	UserInfo Endpoint described in the OpenID spec. Must use `https`.

Token Options

The OAuth server generates two kinds of tokens:

Access tokens	Longer-lived tokens that grant access to the API.
Authorize codes	Short-lived tokens whose only use is to be exchanged for an access token.

Use the tokenConfig stanza to set token options:

Example 13. Master Configuration Token Options

oauthConfig:
  ...
  tokenConfig:
    accessTokenMaxAgeSeconds: 86400 (1)
    authorizeTokenMaxAgeSeconds: 300 (2)

1	Set `accessTokenMaxAgeSeconds` to control the lifetime of access tokens. The default lifetime is 24 hours.
2	Set `authorizeTokenMaxAgeSeconds` to control the lifetime of authorize codes. The default lifetime is five minutes.

Grant Options

To configure how the OAuth server responds to token requests for a client the user has not previously granted permission, set the method value in the grantConfig stanza. Valid values for method are:

`auto`	Auto-approve the grant and retry the request.
`prompt`	Prompt the user to approve or deny the grant.
`deny`	Auto-deny the grant and return a failure error to the client.

Example 14. Master Configuration Grant Options

oauthConfig:
  ...
  grantConfig:
    method: auto

Session Options

The OAuth server uses a signed and encrypted cookie-based session during login and redirect flows.

Use the sessionConfig stanza to set session options:

Example 15. Master Configuration Session Options

oauthConfig:
  ...
  sessionConfig:
    sessionMaxAgeSeconds: 300 (1)
    sessionName: ssn (2)
    sessionSecretsFile: "..." (3)

1	Controls the maximum age of a session; sessions auto-expire once a token request is complete. If auto-grant is not enabled, sessions must last as long as the user is expected to take to approve or reject a client authorization request.
2	Name of the cookie used to store the session.
3	File name containing serialized `SessionSecrets` object. If empty, a random signing and encryption secret is generated at each server start.

If no sessionSecretsFile is specified, a random signing and encryption secret is generated at each start of the master server. This means that any logins in progress will have their sessions invalidated if the master is restarted. It also means that if multiple masters are configured, they will not be able to decode sessions generated by one of the other masters.

To specify the signing and encryption secret to use, specify a sessionSecretsFile. This allows you separate secret values from the configuration file and keep the configuration file distributable, for example for debugging purposes.

Multiple secrets can be specified in the sessionSecretsFile to enable rotation. New sessions are signed and encrypted using the first secret in the list. Existing sessions are decrypted and authenticated by each secret until one succeeds.

Example 16. Session Secret Configuration:

apiVersion: v1
kind: SessionSecrets
secrets: (1)
- authentication: "..." (2)
  encryption: "..." (3)
- authentication: "..."
  encryption: "..."
...

1	List of secrets used to authenticate and encrypt cookie sessions. At least one secret must be specified. Each secret must set an authentication and encryption secret.
2	Signing secret, used to authenticate sessions using HMAC. Recommended to use a secret with 32 or 64 bytes.
3	Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256.