$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
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.
By default, only a kubeadmin
user exists on your cluster. To specify an
identity provider, you must create a custom resource (CR) that describes
that identity provider and add it to the cluster.
OpenShift Container Platform user names containing |
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.
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:
${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}
As of OpenShift Container Platform 4.1, your proxy must support mutual TLS. |
Using SSPI connection support on Microsoft Windows is a Technology Preview feature. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information on Red Hat Technology Preview features support scope, see https://access.redhat.com/support/offerings/techpreview/. |
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.
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.
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.
$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
You can alternatively apply the following YAML to create the config map:
|
The following custom resource (CR) shows the parameters and acceptable values for a request header identity provider.
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: requestheaderidp (1)
mappingMethod: claim (2)
type: RequestHeader
requestHeader:
challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" (3)
loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" (4)
ca: (5)
name: ca-config-map
clientCommonNames: (6)
- my-auth-proxy
headers: (7)
- X-Remote-User
- SSO-User
emailHeaders: (8)
- X-Remote-User-Email
nameHeaders: (9)
- X-Remote-User-Display-Name
preferredUsernameHeaders: (10)
- X-Remote-User-Login
1 | This provider name is prefixed to the user name in the request header to form an identity name. | ||
2 | Controls how mappings are established between this provider’s identities and User objects. |
||
3 | Optional: URL to redirect unauthenticated /oauth/authorize requests to,
that will authenticate browser-based clients and then proxy their request to
https://<namespace_route>/oauth/authorize .
The URL that proxies to https://<namespace_route>/oauth/authorize must end with /authorize (with no trailing slash),
and also proxy subpaths, in order for OAuth approval flows to work properly.
${url} is replaced with the current URL, escaped to be safe in a query parameter.
${query} is replaced with the current query string.
If this attribute is not defined, then loginURL must be used. |
||
4 | Optional: URL to redirect unauthenticated /oauth/authorize requests to,
that will authenticate clients which expect WWW-Authenticate challenges, and
then proxy them to https://<namespace_route>/oauth/authorize .
${url} is replaced with the current URL, escaped to be safe in a query parameter.
${query} is replaced with the current query string.
If this attribute is not defined, then challengeURL must be used. |
||
5 | Reference to an OpenShift Container Platform ConfigMap object containing a PEM-encoded
certificate bundle. Used as a trust anchor to validate the TLS
certificates presented by the remote server.
|
||
6 | Optional: list of common names (cn ). If set, a valid client certificate with
a Common Name (cn ) in the specified list must be presented before the request headers
are checked for user names. If empty, any Common Name is allowed. Can only be used in combination
with 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. |
See Identity provider parameters for information on parameters, such as mappingMethod
, that are common to all identity providers.
After you install your cluster, add an identity provider to it so your users can authenticate.
Create an OpenShift Container Platform cluster.
Create the custom resource (CR) for your identity providers.
You must be logged in as an administrator.
Apply the defined CR:
$ oc apply -f </path/to/CR>
If a CR does not exist, |
Log in to the cluster as a user from your identity provider, entering the password when prompted.
$ oc login -u <username>
Confirm that the user logged in successfully, and display the user name.
$ oc whoami
This example configures an Apache authentication proxy for the OpenShift Container Platform using the request header identity provider.
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?…
.
The |
This example uses the mod_auth_gssapi
module to configure an Apache
authentication proxy using the request header identity provider.
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:
$ 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. |
You can alternatively apply the following YAML to create the config map:
|
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.
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