About identity providers in OpenShift Container Platform

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 /, :, and % are not supported.

To define an HTPasswd identity provider you must perform the following steps:

Creating an HTPasswd file using Linux

To use the HTPasswd identity provider, you must generate a flat file that contains the user names and passwords for your cluster by using htpasswd.

Prerequisites
  • Have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by installing the httpd-tools package.

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!
    Example output
    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>

Creating an HTPasswd file using Windows

To use the HTPasswd identity provider, you must generate a flat file that contains the user names and passwords for your cluster by using htpasswd.

Prerequisites
  • Have access to htpasswd.exe. This file is included in the \bin directory of many Apache httpd distributions.

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!
    Example output
    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>

Creating the HTPasswd secret

To use the HTPasswd identity provider, you must define a secret that contains the HTPasswd user file.

Prerequisites
  • Create an HTPasswd file.

Procedure
  • Create a Secret object that contains the HTPasswd users file:

    $ oc create secret generic htpass-secret --from-file=htpasswd=<path_to_users.htpasswd> -n openshift-config (1)
    1 The secret key containing the users file for the --from-file argument must be named htpasswd, as shown in the above command.

    You can alternatively apply the following YAML to create the secret:

    apiVersion: v1
    kind: Secret
    metadata:
      name: htpass-secret
      namespace: openshift-config
    type: Opaque
    data:
      htpasswd: <base64_encoded_htpasswd_file_contents>

Sample HTPasswd CR

The following custom resource (CR) shows the parameters and acceptable values for an HTPasswd identity provider.

HTPasswd CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: my_htpasswd_provider (1)
    mappingMethod: claim (2)
    type: HTPasswd
    htpasswd:
      fileData:
        name: htpass-secret (3)
1 This provider name is prefixed to provider user names to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
3 An existing secret containing a file generated using htpasswd.
Additional resources

Adding an identity provider to your clusters

After you install your cluster, add an identity provider to it so your users can authenticate.

Prerequisites
  • Create an OpenShift Container Platform cluster.

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

  • You must be logged in as an administrator.

Procedure
  1. Apply the defined CR:

    $ oc apply -f </path/to/CR>

    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

Updating users for an HTPasswd identity provider

You can add or remove users from an existing HTPasswd identity provider.

Prerequisites
  • You have created a Secret object that contains the HTPasswd user file. This procedure assumes that it is named htpass-secret.

  • You have configured an HTPasswd identity provider. This procedure assumes that it is named my_htpasswd_provider.

  • You have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by installing the httpd-tools package.

  • You have cluster administrator privileges.

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

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

    • To add a new user:

      $ htpasswd -bB users.htpasswd <username> <password>
      Example output
      Adding password for user <username>
    • 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:

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

    You can alternatively 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 additionally remove existing resources for each user.

    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

Configuring identity providers using the web console

Configure your identity provider (IDP) through the web console instead of the CLI.

Prerequisites
  • You must be logged in to the web console as a cluster administrator.

Procedure
  1. Navigate to AdministrationCluster 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.

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