Red Hat OpenShift Administration III: Scaling Deployments in the Enterprise

OIDC relies on the JavaScript Object Signing and Encryption (JOSE) set of standards. The primary standard within JOSE is JSON Web Token (JWT), which serves as a standardized format for representing information in a readable piece of text data. The following list shows some JWT advantages:

Three parts, which are separated by a period, form the JWT token: the header, the payload, and the hash signature.

The header contains the type of the token and the signing algorithm.

The payload contains the user claims. User claims are attributes for the user with details about their identity, profile, privileges, and group membership. Examples of user claims are the sub, iat, exp, or iss parameters, which are the identity for the user, the issue date, the expiration date, and the token issuer, respectively.

Finally, the signature is composed of the concatenation of the encoded header, the encoded payload, and the result of applying a signing algorithm.

An identity broker is a service that connects clients with IdPs. The identity broker delegates the authentication of the user to the external IdP. OpenShift includes a built-in OAuth server that you can configure to determine the user's identity from the configured IdPs. Thus, the OpenShift built-in OAuth server acts as an identity broker.

When a user tries to log in to OpenShift, the OpenShift built-in OAuth server redirects the user to a login screen to choose from the configured IdPs. For OIDC IdPs, you must previously configure the OIDC client in the IdP that authenticates the user to OpenShift. Then, use the connection parameters and credentials from the OIDC client to configure the OIDC IdP in the OpenShift built-in OAuth server. After authenticating the user in the configured IdP, the internal OAuth server creates an access token for the request and returns the token. The built-in OAuth server, as for any other IdP, also creates or updates the user resources. If you define OIDC group claims, then the OAuth server also creates or updates the groups.

OIDC claims are key/value pairs that contain information about the user. OpenShift reads user claims from the JWT token that the IdP issues, and uses these user claims to populate the user, identity, and group resources. You must configure one claim to use as the user's identity. The default identity claim is sub, which stands for subject identifier.

You can configure additional user parameters in other standard claims, such as the preferred username, display name, or email address. For any of those user parameters, you can specify multiple claims. OpenShift uses the first claim with a non-empty value.

The following table lists some standard claims that are defined in OIDC:

You can also define additional claims for parameters that OIDC does not define as standard claims. One important additional claim for users is the group claim. OpenShift uses the group claim to map the group membership of a user in the IdP to a group object. Then, you can use role-based access control (RBAC) objects in OpenShift to assign permissions to that group, instead of assigning permissions to individual users.

After creating the OpenShift secret object that contains the client secret, and the configuration object that contains the certificate authority bundle (if necessary), you can create the OAuth CR YAML file that contains the information to configure the OIDC IdP. If you add an OIDC IdP to the OAuth CR, then you must include the OIDC IdP information in the identityProviders array. You can add multiple OIDC IdPs to the OAuth CR YAML file.

The following example shows a minimal configuration file for Red Hat SSO integration to OpenShift. The settings might differ for other OIDC providers, and you must work with your vendor or identity administrator to get all the necessary attributes for your specific setup.

apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: oidc_provider_name 
    mappingMethod: claim
    type: OpenID
    openID:
      clientID: oidc_clientid 
      clientSecret: 
        name: secret_name
      ca: 
        name: config_map_name
      claims: 
        preferredUsername:
        - preferred_username
        - email
        name:
        - nickname
        - given_name
        - name
        email:
        - custom_email_claim
        - email
        groups:
        - groups
      issuer: https://external_idp_url.com 

After adding the OIDC IdP to the cluster, you can log in through the IdP by using the OpenShift web console, and providing the username and the password.

If your OIDC IdP supports the grant flow for resource owner password credentials (ROPC), then you can also log in through the IdP by using the oc login command with the username and the password.

If your OIDC IdP does not support the ROPC grant flow, then you receive a You must obtain an API token login error when you use the oc login command with the username and the password. Then, you must first get an OAuth access token and use it to log in by using the oc login --token=acces_token command. You can get the OAuth access token by logging in through the OpenShift web console and then clicking Help → Command line tools → Copy login command. You can also request the OAuth access token through the OpenShift REST API.

IdP mapping methods apply to any IdP. If you configure the mappingMethod parameter for the OIDC IdP as claim or add, then OpenShift establishes mappings between the provider's identity and the User object the first time that a user logs in to the cluster.

The first time that a user logs in to the cluster, the OpenShift built-in OAuth server creates an OAuth token to authenticate to the API. OAuth access tokens are common to any IdP. OpenShift renews the token to authenticate to the API every time that the user logs in to the cluster. As a user, you can list all your user-owned OAuth access tokens by using the following command. This command lists all the user-owned OAuth access tokens from any IdP that is configured in the OpenShift built-in OAuth server.

[user@host ~]$ oc get useroauthaccesstokens
NAME            CLIENT NAME    CREATED   EXPIRES                        ...
sha256~9BZ3...  openshift-...  69m       2023-06-14 13:24:42 +0000 UTC  ...
sha256~lm1O...  console        75m       2023-06-14 13:19:20 +0000 UTC  ...
sha256~xmpC...  openshift-...  83m       2023-06-14 13:11:24 +0000 UTC  ...

If you modify a user parameter in the OIDC IdP, then the OIDC IdP does not automatically synchronize to OpenShift. For example, if you remove a user account from the OIDC IdP and the user is logged in to OpenShift, then the user can still perform tasks in OpenShift until they log out, because they still have a valid token that the OpenShift built-in OAuth server emits.

For this reason, after you modify a parameter in the OIDC IdP, you must manually remove all the user access tokens from OpenShift to force a user logout. Then, after the user logs in again, OpenShift synchronizes the new user parameters.

You can use the following command to remove all the user access tokens from OpenShift:

[user@host ~]$ oc delete oauthaccesstoken $(oc get oauthaccesstoken -o \
  jsonpath='{.items[?(@.userName=="username")].metadata.name}')