Chapter 7. Configuring identity providers

1. Create an htpasswd file to store the user and password information. Instructions are provided for Linux and Windows.
2. Create an OpenShift Container Platform secret to represent the htpasswd file.
3. Define the HTPasswd identity provider resource.
4. Apply the resource to the default OAuth configuration.

Procedure

1. Create or update your flat file with a user name and hashed password:

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

   The command generates a hashed version of the password.

   For example:

   $ htpasswd -c -B -b users.htpasswd user1 MyPassword!
   
   Adding password for user user1

2. Continue to add or update credentials to the file:

   $ htpasswd -B -b </path/to/users.htpasswd> <user_name> <password>

Procedure

1. Create or update your flat file with a user name and hashed password:

   > htpasswd.exe -c -B -b <\path\to\users.htpasswd> <user_name> <password>

   The command generates a hashed version of the password.

   For example:

   > htpasswd.exe -c -B -b users.htpasswd user1 MyPassword!
   
   Adding password for user user1

2. Continue to add or update credentials to the file:

   > htpasswd.exe -b <\path\to\users.htpasswd> <user_name> <password>

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

Procedure

1. Retrieve the HTPasswd file from the htpass-secret secret and save the file to your file system:

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

2. Add or remove users from the users.htpasswd file.

   • To add a new user:

     $ htpasswd -bB users.htpasswd <username> <password>
     Adding password for user <username>

   • To remove an existing user:

     $ htpasswd -D users.htpasswd <username>
     Deleting password for user <username>

3. Replace the htpass-secret secret with the updated users in the users.htpasswd file:

   $ oc create secret generic htpass-secret --from-file=htpasswd=users.htpasswd --dry-run -o yaml -n openshift-config | oc replace -f -

4. If you removed one or more users, you must additionally remove existing resources for each user.

   1. Delete the user:

      $ oc delete user <username>
      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 for the user:

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

Procedure

1. Navigate to Administration Cluster Settings.
2. Under the Global Configuration tab, click OAuth.
3. Under the Identity Providers section, select your identity provider from the Add drop-down menu.

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

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

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

1. Create the certificate for the Apache configuration. The certificate that you specify as the SSLProxyMachineCertificateFile parameter value is the proxy’s client certificate that is used to authenticate the proxy to the server. It must use TLS Web Client Authentication as the extended key type.

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

   Important

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

   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.

3. Update the identityProviders stanza in 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

4. Verify the configuration.

   1. Confirm that you can bypass the proxy by requesting a token by supplying the correct client certificate and header:

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

   2. Confirm that requests that do not supply the client certificate fail by requesting a token without the certificate:

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

   3. Confirm that the challengeURL redirect is active:

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

      Copy the challengeURL redirect to use in the next step.

   4. Run this command to show a 401 response with a WWW-Authenticate basic challenge, a negotiate challenge, or both challenges:

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

   5. Test logging in to the OpenShift CLI (oc) with and without using a Kerberos ticket:

      1. If you generated a Kerberos ticket by using kinit, destroy it:

         # kdestroy -c cache_name 1

         1

         Make sure to provide the name of your Kerberos cache.

      2. Log in to the oc tool by using your Kerberos credentials:

         # oc login

         Enter your Kerberos user name and password at the prompt.

      3. Log out of the oc tool:

         # oc logout

      4. Use your Kerberos credentials to get a ticket:

         # kinit

         Enter your Kerberos user name and password at the prompt.

      5. Confirm that you can log in to the oc tool:

         # oc login

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

Procedure

1. Register an application on GitHub:

   • For GitHub, click Settings Developer settings OAuth Apps Register a new OAuth application.
   • For GitHub Enterprise, go to your GitHub Enterprise home page and then click Settings Developer settings Register a new application.
2. Enter an application name, for example My OpenShift Install.
3. Enter a homepage URL, such as https://oauth-openshift.apps.<cluster-name>.<cluster-domain>.
4. Optional: Enter an application description.

5. 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.example-openshift-cluster.com/oauth2callback/github/

6. Click Register application. GitHub provides a Client ID and a Client Secret. You need these values to complete the identity provider configuration.

Procedure

1. Apply the defined CR:

   $ 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, passing in the token to authenticate.

   $ oc login --token=<token>

   Note

   This identity provider does not support logging in with a user name and password.

4. Confirm that the user logged in successfully, and display the user name.

   $ oc whoami

Procedure

1. Apply the defined CR:

   $ 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 display the user name.

   $ oc whoami

Procedure

1. Apply the defined CR:

   $ 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, passing in the token to authenticate.

   $ oc login --token=<token>

   Note

   This identity provider does not support logging in with a user name and password.

4. Confirm that the user logged in successfully, and display the user name.

   $ oc whoami

Procedure

1. Apply the defined CR:

   $ 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, passing in the token to authenticate.

   $ oc login --token=<token>

   Note

   This identity provider does not support logging in with a user name and password.

4. Confirm that the user logged in successfully, and display the user name.

   $ oc whoami

Procedure

1. Navigate to Administration Cluster Settings.
2. Under the Global Configuration tab, click OAuth.
3. Under the Identity Providers section, select your identity provider from the Add drop-down menu.