Configuring an OpenID Connect identity provider - Configuring identity providers | Authentication and authorization

Identity providers in OKD
About OpenID Connect authentication
Creating the secret
Creating a ConfigMap
Sample OpenID Connect CRs
- Standard OIDC CR
- Full OpenID CR
Adding an identity provider to your cluster
Configuring identity providers using the web console
Additional resources

To integrate OKD with an external OpenID Connect (OIDC) identity provider, configure the oidc identity provider by using the Authorization Code Flow. Use this integration when your organization already uses OIDC for single sign-on.

Identity providers in OKD

You can configure identity providers by creating a custom resource (CR) that describes the provider and adding it to the cluster. Identity providers enable user authentication in OKD beyond the default kubeadmin user.

OKD usernames containing /, :, and % are not supported.

About OpenID Connect authentication

Review OpenID Connect (OIDC) discovery, scopes, and claim mapping before you configure the oidc identity provider. OIDC support and correctly mapped claims are required for the Authentication Operator to authenticate users in OKD.

The Authentication Operator in OKD requires that the configured OIDC identity provider implements the OIDC discovery specification. For more information, see "OpenID Connect Discovery".

You can configure a Keycloak server as an OpenID Connect identity provider for OKD.

ID Token and UserInfo decryptions are not supported.

By default, the openid scope is requested. If required, extra scopes can be specified in the extraScopes field.

Claims are read from the JWT id_token returned from the OpenID identity provider and, if specified, from the JSON returned by the UserInfo URL.

At least one claim must be configured to use as the identity of the user. The standard identity claim is sub.

You can also indicate which claims to use as the preferred username, display name, and email address of the user. If multiple claims are specified, the first one with a non-empty value is used. The following table lists the standard claims:

Claim Description

Claim	Description
`sub`	Short for "subject identifier." The remote identity for the user at the issuer.
`preferred_username`	The preferred username when provisioning a user. A shorthand name that the user wants to be referred to, such as `janedoe`. Typically a value that corresponds to the login or username of the user in the authentication system, such as username or email.
`email`	Email address.
`name`	Display name.

sub

Short for "subject identifier." The remote identity for the user at the issuer.

preferred_username

The preferred username when provisioning a user. A shorthand name that the user wants to be referred to, such as janedoe. Typically a value that corresponds to the login or username of the user in the authentication system, such as username or email.

email

Email address.

name

Display name.

For more information, see "OpenID claims documentation".

Unless your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, users must get a token from <namespace_route>/oauth/token/request to use with command-line tools.

Additional resources

Creating the secret

Create a Secret object in the openshift-config namespace to store the client secret for your identity provider. The identity provider custom resource (CR) references this secret during configuration.

Procedure

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

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>

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

Creating a ConfigMap

Create a ConfigMap object in the openshift-config namespace that contains the certificate authority bundle for the identity provider. OKD uses this bundle to validate Transport Layer Security (TLS) connections to the identity provider.

Procedure

Define an OKD 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

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.

Sample OpenID Connect CRs

Review the sample OpenID Connect (OIDC) custom resources (CRs) before you configure the oidc identity provider. These examples show required parameters, acceptable values, and optional fields such as custom certificate bundles and extra scopes.

If you must specify a custom certificate bundle, extra scopes, extra authorization request parameters, or a userInfo URL, use the full OIDC CR.

Standard OIDC CR

The following is an example of a standard OIDC CR.

apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: oidcidp
    mappingMethod: claim
    type: OpenID
    openID:
      clientID: ...
      clientSecret:
        name: idp-secret
      claims:
        preferredUsername:
        - preferred_username
        name:
        - name
        email:
        - email
        groups:
        - groups
      issuer: https://www.idp-issuer.com

where:

spec.identityProviders.name: Specifies that this provider name is prefixed to the value of the identity claim to form an identity name. It is also used to build the redirect URL.
spec.identityProviders.mappingMethod: Specifies how mappings are established between identities from this provider and User objects.
spec.identityProviders.openID.clientID: Specifies the client ID of a client registered with the OpenID provider. The client must be allowed to redirect to https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>.
spec.identityProviders.openID.clientSecret: Specifies a reference to an OKD Secret object containing the client secret.
spec.identityProviders.openID.claims: Specifies the list of claims to use as the identity. The first non-empty claim is used.
spec.identityProviders.openID.issuer: Specifies the Issuer Identifier described in the OpenID spec. Must use https without query or fragment component. For more information, see "Issuer Identifier".

Full OpenID CR

The following is an example of a full OpenID Connect CR.

apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: oidcidp
    mappingMethod: claim
    type: OpenID
    openID:
      clientID: ...
      clientSecret:
        name: idp-secret
      ca:
        name: ca-config-map
      extraScopes:
      - email
      - profile
      extraAuthorizeParameters:
        include_granted_scopes: "true"
      claims:
        preferredUsername:
        - preferred_username
        - email
        name:
        - nickname
        - given_name
        - name
        email:
        - custom_email_claim
        - email
        groups:
        - groups
      issuer: https://www.idp-issuer.com

where:

spec.identityProviders.openID.ca: Specifies a reference to an OKD config map containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. This value is optional.
spec.identityProviders.openID.extraScopes: Specifies the list of scopes to request, in addition to the openid scope, during the authorization token request. This value is optional.
spec.identityProviders.openID.extraAuthorizeParameters: Specifies a map of extra parameters to add to the authorization token request. This value is optional.
spec.identityProviders.openID.claims.preferredUsername: Specifies the list of claims to use as the preferred username when provisioning a user for this identity. The first non-empty claim is used.
spec.identityProviders.openID.claims.name: Specifies the list of claims to use as the display name. The first non-empty claim is used.
spec.identityProviders.openID.claims.email: Specifies the list of claims to use as the email address. The first non-empty claim is used.
spec.identityProviders.openID.claims.groups: Specifies the list of claims to use to synchronize groups from the OpenID Connect provider to OKD upon user login. The first non-empty claim is used.

Additional resources

Identity provider parameters

Adding an identity provider to your cluster

Apply the identity provider custom resource (CR) to your cluster after you define it. With this configuration, you can authenticate with the configured identity provider.

Prerequisites

You have access to a OKD cluster.
You have created the CR for your identity providers.
You are logged in as an administrator.

Procedure

Apply the defined CR by running the following command:

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

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.

$ oc login --token=<token>

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.

After the OIDC identity provider is configured in OKD, 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.
Confirm that the user logged in successfully and that the username displays by running the following command:
```
$ oc whoami
```

Configuring identity providers using the web console

You can configure identity providers on your OKD cluster through the web console by updating the OAuth settings in the Cluster Settings.

Prerequisites

You are logged in to the web console as a cluster administrator.

Procedure

Navigate to Administration → Cluster Settings.
Under the Configuration tab, click OAuth.
Under the Identity Providers section, select your identity provider from the Add drop-down list.

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