Authentication and authorization

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Retrieve the htpasswd file from the htpass-secret Secret object and save it to your local machine by running the following command:

   $ oc get secret htpass-secret -ojsonpath={.data.htpasswd} -n openshift-config | base64 --decode > users.htpasswd

2. Add or remove users from the users.htpasswd file by running the following commands:

   1. To add a new user:

      $ htpasswd -bB users.htpasswd <username> <password>

      Example output

      Adding password for user <username>

   2. To remove an existing user:

      $ htpasswd -D users.htpasswd <username>

      Example output

      Deleting password for user <username>

3. Replace the htpass-secret Secret object with the updated users in the users.htpasswd file by running the following command:

   $ 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 also 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>

4. If you removed one or more users, you must remove the existing resources for each user by running the following commands:

   1. Delete the User object:

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

   2. Delete the Identity object for the user:

      $ oc delete identity my_htpasswd_provider:<username>

      Example output

      identity.user.openshift.io "my_htpasswd_provider:<username>" deleted

Procedure

1. Navigate to Administration → Cluster Settings.
2. Under the Configuration tab, click OAuth.

3. Under the Identity Providers section, select your identity provider from the Add drop-down list.

   Note

   You can specify multiple identity providers through the web console without overwriting existing identity providers.

Procedure

1. Create a Secret object that contains the key and certificate by running the following command:

   $ oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config

2. Optional: 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>

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

1. Generates a search filter by combining the attribute and filter in the configured url with the user-provided username.
2. Searches the directory using the generated filter. Denies access if the search does not return exactly one entry.
3. Attempts to bind to the LDAP server using the DN of the entry retrieved from the search, and the user-provided password.
4. Denies access if the bind is unsuccessful.
5. Builds an identity using the configured attributes as the identity, email address, display name, and preferred username if the bind is successful.

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Create a Secret object that contains the key and certificate by running the following command:

   $ oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-config

2. Optional: 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>

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. To test successful and unsuccessful logins, replace the <user> and <password> in the following example command with valid or invalid 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

2. Review successful login 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 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 username 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.

3. Review failed login 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"}

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Generate a CA for validating requests that submit the trusted header.

2. Create an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

3. Optional: Apply the following YAML to create the config map. For example:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: ca-config-map
     namespace: openshift-config
   data:
     ca.crt: |
       <CA_certificate_PEM>

   The certificate authority must be stored in the ca.crt key of the ConfigMap object.

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

5. Create the custom resource (CR) for your identity providers.

6. Create the certificate for the Apache configuration.

   The certificate that you specify as the SSLProxyMachineCertificateFile parameter value is the client certificate for the proxy that authenticates the proxy to the server. It must use TLS Web Client Authentication as the extended key type.

7. Create the Apache configuration. Use the following template to provide your required settings and values:

   Important

   Carefully review the template and customize the template contents to fit your environment.

   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     ^(.*)$     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 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} ^$ [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

   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.

8. Update the identityProviders section of the custom resource (CR):

   identityProviders:
     - name: requestheaderidp
       type: RequestHeader
       requestHeader:
         challengeURL: "https://<namespace_route>/challenging-proxy/oauth/authorize?${query}"
         loginURL: "https://<namespace_route>/login-proxy/oauth/authorize?${query}"
         ca:
           name: ca-config-map
         clientCommonNames:
         - my-auth-proxy
         headers:
         - X-Remote-User

Verification

1. Confirm that you can bypass the proxy when you supply the correct client certificate and header by running the following command:

   $ curl -L -k -H "X-Remote-User: joe" \
      --cert /etc/pki/tls/certs/authproxy.pem \
      https://<namespace_route>/oauth/token/request

2. Confirm that requests that do not supply the client certificate fail by running the following command:

   $ curl -L -k -H "X-Remote-User: joe" \
      https://<namespace_route>/oauth/token/request

3. Confirm that the challengeURL redirect is active by running the following command:

   $ 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 next step.

4. Show a 401 response with a WWW-Authenticate basic challenge, a negotiate challenge, or both challenges by running the following command:

   $ curl -k -v -H 'X-Csrf-Token: 1' \
      <challengeURL_redirect + query>

5. If you generated a Kerberos ticket by using kinit, destroy it by running the following command:

   $ kdestroy -c <cache_name>

   Replace <cache_name> with the name of your Kerberos cache.

6. Log in to the OpenShift CLI (oc) with your Kerberos credentials by running the following command:

   $ oc login -u <username>

   Enter your Kerberos username and password at the prompt.

7. Log out of the oc tool by running the following command:

   $ oc logout

8. Use your Kerberos credentials to get a ticket by running the following command:

   $ kinit

   Enter your Kerberos username and password at the prompt.

9. Confirm that you can log in to the oc tool by running the following command:

   $ oc login

   If your configuration is correct, you are logged in without entering separate credentials.

Procedure

1. Start the registration process by navigating to the appropriate page in GitHub or GitHub Enterprise:

   • For GitHub, click your profile picture in the upper right corner and select Settings → Developer settings → OAuth Apps.
   • For GitHub Enterprise, go to your GitHub Enterprise home page and then select Settings → Developer settings → Register a new application.
2. Click New OAuth app.
3. Enter an application name, for example My OpenShift Install.
4. Enter a homepage URL, such as https://oauth-openshift.apps.<cluster-name>.<cluster-domain>.
5. Optional: Enter an application description.

6. Enter the authorization callback URL, where the end of the URL contains the identity provider name:

   https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>

   For example:

   https://oauth-openshift.apps.openshift-cluster.example.com/oauth2callback/github

7. Click Register application. GitHub provides a client ID and a client secret. You need these values to complete the identity provider configuration.

Procedure

1. Create a Secret object containing the client secret by running the following command:

   $ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config

2. Optional: 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>

3. Create a Secret object from a file by running the following command:

   $ oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

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

3. Log in to the cluster by running the following command, passing in the token to authenticate:

   $ oc login --token=<token>

1. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Create a Secret object containing the client secret by running the following command:

   $ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config

2. Optional: 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>

3. Create a Secret object from a file by running the following command:

   $ oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

2. Log in to the cluster as a user from your identity provider, entering the password when prompted.

   $ oc login -u <username>

3. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Create a Secret object containing the client secret by running the following command:

   $ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config

2. Optional: 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>

3. Create a Secret object from a file by running the following command:

   $ oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config

Procedure

1. Apply the defined CR by running the following command:

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

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

3. Log in to the cluster by running the following command, passing in the token to authenticate:

   $ oc login --token=<token>

1. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Create a Secret object containing the client secret by running the following command:

   $ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config

2. Optional: 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>

3. Create a Secret object from a file by running the following command:

   $ oc create secret generic <secret_name> --from-file=<path_to_file> -n openshift-config

Procedure

1. Define an OpenShift Container Platform ConfigMap object containing the CA by running the following command:

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

2. Optional: 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>

   The CA must be stored in the ca.crt key of the ConfigMap object.

Procedure

1. Apply the defined CR by running the following command:

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

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

3. Log in to the cluster by running the following command, passing in the token to authenticate:

   $ 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 username and password. You might need to take steps to enable the ROPC grant flow for your identity provider.

4. After the OIDC identity provider is configured in OpenShift Container Platform, log in by running the following command. The command prompts you for your username and password:

   $ oc login -u <identity_provider_username> --server=<api_server_url_and_port>

   If your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, you might need to take steps to enable the ROPC grant flow for your identity provider.

5. Confirm that the user logged in successfully and that the username displays by running the following command:

   $ oc whoami

Procedure

1. Navigate to Administration → Cluster Settings.
2. Under the Configuration tab, click OAuth.

3. Under the Identity Providers section, select your identity provider from the Add drop-down list.

   Note

   You can specify multiple identity providers through the web console without overwriting existing identity providers.