Understanding identity provider configuration

As an administrator, you can configure OAuth to specify an identity provider after you install your cluster.

By default, only a 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.

You can configure the following types of identity providers:

Identity provider	Description
HTPasswd	Configure the `htpasswd` identity provider to validate user names and passwords against a flat file generated using .
Keystone	Configure the `keystone` identity provider to integrate your OKD cluster with Keystone to enable shared authentication with an OpenStack Keystone v3 server configured to store users in an internal database.
	Configure the `ldap` identity provider to validate user names and passwords against an LDAPv3 server, using simple bind authentication.
Basic authentication	Configure a `basic-authentication` identity provider for users to log in to OKD with credentials validated against a remote identity provider. Basic authentication is a generic backend integration mechanism.

GitHub or GitHub Enterprise	Configure a `github` identity provider to validate user names and passwords against GitHub or GitHub Enterprise’s OAuth authentication server.
	Configure a `gitlab` identity provider to use GitLab.com or any other GitLab instance as an identity provider.
	Configure a identity provider using Google’s OpenID Connect integration.
	Configure an `oidc` identity provider to integrate with an OpenID Connect identity provider using an Authorization Code Flow.

Once an identity provider has been defined, you can .

After you define an identity provider and create a new cluster-admin user, you can remove the kubeadmin to improve cluster security.

Prerequisites

You must have configured at least one identity provider.
You must be logged in as an administrator.

Procedure

Remove the kubeadmin secrets:

The following parameters are common to all identity providers:

Parameter Description

Parameter	Description
`name`	The provider name is prefixed to provider user names to form an identity name.
`mappingMethod`	Defines how new identities are mapped to users when they log in. Enter one of the following values: 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. Using this method requires you to manually provision users. 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 OKD 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.

name

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

mappingMethod

Defines how new identities are mapped to users when they log in. Enter one of the following values:

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. Using this method requires you to manually provision users.

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

The following custom resource (CR) shows the parameters and default values that you use to configure an identity provider. This example uses the HTPasswd identity provider.

apiVersion: config.openshift.io/v1
metadata:
  name: cluster
  identityProviders:
  - name: my_identity_provider (1)
    mappingMethod: claim (2)
    type: HTPasswd
    htpasswd:
      fileData:

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