Red Hat OpenShift Container Platform

Configuring an external OIDC identity provider for direct authentication

Configure Red Hat OpenShift Container Platform to use an external OIDC identity provider for direct authentication, enabling users to log in with existing corporate credentials while bypassing the built-in OAuth server for streamlined single sign-on.

Prerequisites

You have configured your external authentication provider.

This procedure uses Keycloak as the identity provider and assumes that you have the following clients configured:
- A confidential client for the web console called console-test with the valid redirect URIs set to https://<openshift_console_route>/auth/callback
- A public client for the OpenShift CLI (oc) called oc-cli-test with the valid redirect URIs set to http://localhost:8080
You have access to the kubeconfig file generated by the installation program for the cluster.
You have backed up any existing authentication configuration, in case you need to revert back to using the built-in OAuth server for authentication.
You have the Red Hat OpenShift Container Platform web console enabled on the cluster.

If the web console is not enabled in your cluster, see "Example OIDC provider configuration for CLI clients only" for an example configuration without the web console client.

Procedure

Ensure that you are using the kubeconfig file generated by the installation program, or another long-lived method of logging in as a cluster administrator.
Create a secret that allows you to authenticate with the web console by running the following command:
```
$ oc create secret generic console-secret \
    --from-literal=clientSecret=<secret_value> \//
    -n openshift-config
```
Replace <secret_value> with the value of the secret for the console-test client in your identity provider.
Optional: Create a config map that contains the provider’s certificate authority bundle by running the following command:
```
$ oc create configmap keycloak-oidc-ca --from-file=ca-bundle.crt=my-directory/ca-bundle.crt \
    -n openshift-config
```
Specify the path to your provider’s ca-bundle.crt file.
Edit the authentication configuration by running the following command:
```
$ oc edit authentication.config/cluster
```
Update the authentication configuration by setting the type field to OIDC, configuring the oidcProviders field for your provider, and setting the webhookTokenAuthenticator field to null:
```
apiVersion: config.openshift.io/v1
kind: Authentication
metadata:
# ...
spec:
  type: OIDC
  webhookTokenAuthenticator: null
  oidcProviders:
  - claimMappings:
      extra:
      - key: example.com/role
        valueExpression: claims.?role.orValue("unknown")
      groups:
        claim: groups
        prefix: 'oidc-groups-test:'
      uid:
        claim: "sub"
      username:
        claim: email
        prefixPolicy: Prefix
        prefix:
          prefixString: 'oidc-user-test:'
    issuer:
      audiences:
      - console-test
      - oc-cli-test
      issuerCertificateAuthority:
        name: keycloak-oidc-ca
      issuerURL: https://keycloak-keycloak.apps.example.com/realms/master
    name: 'keycloak-oidc-server'
    oidcClients:
    - clientID: oc-cli-test
      componentName: cli
      componentNamespace: openshift-console
    - clientID: console-test
      clientSecret:
        name: console-secret
      componentName: console
      componentNamespace: openshift-console
      extraScopes:
        - email
        - profile
```
where:

spec.type

Specifies the authentication type. Must be set to OIDC to indicate to use an external OIDC identity provider.

spec.webhookTokenAuthenticator

Specifies the webhook token authenticator configuration. Must be set to null when type is set to OIDC.

spec.oidcProviders

Specifies the OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.

spec.oidcProviders.claimMappings.extra

Specifies the mappings used to construct the extra attributes for the cluster identity. This field is optional.

spec.oidcProviders.claimMappings.groups.claim

Specifies the name of the claim to construct group names for the cluster identity.

spec.oidcProviders.claimMappings.uid

Specifies the claim mapping used to construct the UID for the cluster identity. This field is optional.

spec.oidcProviders.claimMappings.username.claim

Specifies the name of the claim to construct usernames for the cluster identity.

spec.oidcProviders.issuer.audiences

Specifies the list of audiences that this authentication provider issues tokens for.

spec.oidcProviders.issuer.issuerCertificateAuthority.name

Specifies the name of the config map that contains the ca-bundle.crt key. If unset, system trust is used instead.

spec.oidcProviders.issuer.issuerURL

Specifies the URL for the token issuer.

spec.oidcProviders.name

Specifies the name for external OIDC provider.

spec.oidcProviders.oidcClients.clientID

Specifies the client ID that your provider uses. Configure separate entries for the OpenShift CLI (oc) and the Red Hat OpenShift Container Platform web console.

spec.oidcProviders.oidcClients.clientSecret.name

Specifies the name of the secret that stores the secret value for the console client.

spec.oidcProviders.oidcClients.extraScopes

Specifies the extra scopes to request. Some providers, such as GitLab, might require extra scopes in order to log in through the web console properly.
Exit and save the changes to apply the new configuration.
Wait for the cluster to roll out new revisions to all nodes.
1. Check the Kubernetes API server Operator status by running the following command:
  $ oc get co kube-apiserver
  Example output
  NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE kube-apiserver 4.22.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 8; 1 node is at revision 10
  The message in the preceding example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 20 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
2. To troubleshoot any issues, you can also check the Cluster Authentication Operator and kube-apiserver pod logs for errors.

Verification

Verify that you can log in to the OpenShift CLI (oc) by authenticating with your identity provider:
1. Log in by running the following command:
  $ oc login --exec-plugin=oc-oidc \ --issuer-url=https://keycloak-keycloak.apps.example.com/realms/master \ --client-id=oc-cli-test \ --extra-scopes=email --callback-port=8080 \ --oidc-certificate-authority my-directory/ca-bundle.crt
  where:
  --exec-plugin
  
  Specifies the exec plugin type. Only a value of oc-oidc is allowed.
  
  --issuer-url
  
  Specifies the issuer URL for your identity provider.
  
  --client-id
  
  Specifies the client ID for the OpenShift CLI (oc).
  
  --oidc-certificate-authority
  
  Specifies the path to the ca-bundle.crt file on your local machine.
  
  Example output
  
  Please visit the following URL in your browser: http://localhost:8080
2. Open http://localhost:8080 in a browser.
3. Authenticate with credentials from your identity provider.
  
  After successfully authenticating, you should see a message similar to the following output in your terminal:
  Logged into "https://api.my-cluster.example.com:6443" as "oidc-user-test:user1@example.com" from an external oidc issuer.
Verify that you can log in to the Red Hat OpenShift Container Platform web console by authenticating with your identity provider:
1. Open the web console URL for your cluster in a browser.
  
  You are redirected to your identity provider to log in.
2. Authenticate with credentials from your identity provider.
  
  Verify that you logged in successfully and are redirected to the Red Hat OpenShift Container Platform web console.

OIDC provider configuration parameters

Configure OIDC providers for external authentication by using these parameters to map JWT token claims to cluster identities, validate authentication tokens, and enable platform components to authenticate with identity providers.

The following table lists all available OIDC provider parameters for direct authentication:

Table 12. `oidcProviders` configuration
Parameter	Description
`claimMappings`	Configures the rules to be used by the Kubernetes API server for translating claims in a JSON web token (JWT), issued by the identity provider, to a cluster identity.
`claimMappings.extra`	An optional field for configuring the mappings used to construct the extra attribute for the cluster identity. When omitted, no extra attributes will be present on the cluster identity. Key values for extra mappings must be unique. A maximum of 32 extra attribute mappings can be provided.
`claimMappings.extra.key`	A required field that specifies the string to use as the extra attribute key. The following restrictions apply: Key must be a domain-prefix path (e.g `example.org/foo`). Key must not exceed 510 characters in length. Key must contain the `/` character, separating the domain and path characters. Key must not be empty. The domain portion of the key (string of characters before the `/`) must be a valid RFC1123 subdomain. It must not exceed 253 characters in length. It must start and end with an alphanumeric character. It must only contain lower case alphanumeric characters and `-` or `.`. It must not use the reserved domains, or be subdomains of, `kubernetes.io`, `k8s.io`, and `openshift.io`. The path portion of the key (string of characters after the `/`) must not be empty and must consist of at least one alphanumeric character, percent-encoded octets, `-`, `.`, `_`, `~`, `!`, `$`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `;`, `=`, and `:`. Domain portion of the key must not exceed 256 characters in length.
`claimMappings.extra.valueExpression`	A required field to specify the CEL expression to extract the extra attribute value from claims of a JWT token. The `valueExpression` field must produce a string or string array value. The following restrictions apply: CEL expressions that return "", [], and null are treated as the extra mapping not being present. Empty string values within an array are filtered out. For example, [`one`, `, `three] becomes [`one`, `three`]. CEL expressions have access to the token claims through a CEL variable, `claims`. `claims` is a map of claim names to claim values. For example, the `sub` claim value can be accessed as `claims.sub`. Nested claims can be accessed using dot notation (`claims.foo.bar`). The `valueExpression` value must not exceed 1024 characters in length. The `valueExpression` value must not be empty.
`claimMappings.groups`	Configures how the groups of a cluster identity should be constructed from the claims in a JWT token issued by the identity provider. When referencing a claim, if the claim is present in the JWT token, its value must be a comma-separated list of groups.
`claimMappings.groups.claim`	Optional parameter. JWT token claim used for groups mapping. Set either `claim` or `expression`, not both. Length: 1-256 characters.
`claimMappings.groups.expression`	Optional parameter (Technology Preview). CEL expression that produces a string or string array from JWT token claims. Access claims by using the `claims` variable (for example, `claims.groups` or `claims.foo.bar` for nested claims). Set either `claim` or `expression`, not both. Length: 1-1024 characters.
`claimMappings.groups.prefix`	Configures the prefix that is applied to the cluster identity attribute during the process of mapping JWT claims to cluster identity attributes.
`claimMappings.uid`	An optional field for configuring the claim mapping used to construct the UID for the cluster identity. When omitted, this means the user has no opinion and the platform is left to choose a default, which is subject to change over time. The current default is to use the `sub` claim.
`claimMappings.uid.claim`	An optional field for specifying the JWT token claim that is used in the mapping. The value of this claim will be assigned to the field in which this mapping is associated. To specify the claim, use a single string value for `uid.claim`. You must set either `claim` or `expression`. Do not specify `claim` when `expression` is set. The value of `claim` must be at least 1 character and must not exceed 256 characters in length.
`claimMappings.uid.expression`	An optional field for specifying a CEL expression that produces a string value from JWT token claims. When using `uid.expression` the expression must result in a single string value. CEL expressions have access to the token claims through a CEL variable, `claims`. The `claims` variable is a map of claim names to claim values. For example, you can access the `sub` claim value as `claims.sub`. Nested claims can be accessed using dot notation for example, `claims.foo.bar`. You must set either `claim` or `expression`. Do not specify `expression` when `claim` is set. The value of `expression` must be at least 1 character and must not exceed 1024 characters in length.
`claimMappings.username`	Configures how the username of a cluster identity should be constructed from the claims in a JWT token issued by the identity provider.
`claimMappings.username.claim`	Optional parameter. JWT token claim used for username mapping. Set either `claim` or `expression`, not both. Length: 1-256 characters.
`claimMappings.username.expression`	Optional parameter (Technology Preview). CEL expression that produces a string value from JWT token claims. Must result in a single string. Access claims by using the `claims` variable (for example, `claims.email` or `claims.foo.bar` for nested claims). Set either `claim` or `expression`, not both. Length: 1-1024 characters.
`claimMappings.username.prefix`	Configures the prefix that should be prepended to the value of the JWT claim. Must be set when `prefixPolicy` is set to `Prefix` and must be unset otherwise.
`claimMappings.username.prefix.prefixString`	Configures the prefix that is applied to the cluster identity username attribute during the process of mapping JWT claims to cluster identity attributes. Must not be an empty string (`""`).
`claimMappings.username.prefixPolicy`	Configures how a prefix should be applied to the value of the JWT claim specified in the `claim` field. Allowed values are `Prefix`, `NoPrefix`, and omitted (not provided or an empty string). When set to `Prefix`, the value specified in the prefix field is prepended to the value of the JWT claim. The prefix field must be set when `prefixPolicy` is `Prefix`. When set to `NoPrefix`, no prefix is prepended to the value of the JWT claim. When omitted, this means no opinion and the platform is left to choose any prefixes that are applied which is subject to change over time. Currently, the platform prepends `{issuerURL}#` to the value of the JWT claim when the claim is not `email`.
`claimValidationRules`	Configures the rules to be used by the Kubernetes API server for validating the claims in a JWT token issued by the identity provider. Validation rules are joined by an `AND` operation.
`claimValidationRules.cel`	Optional parameter (Technology Preview). Required when `type` is `CEL`. Contains `expression` (CEL expression to evaluate) and `message` (error text).
`claimValidationRules.cel.expression`	Technology Preview. CEL expression that validates token claims. Must evaluate to `true` for authentication to succeed. Access claims by using the `claims` variable using dot notation (for example, `claims.sub` or `claims.foo.bar`). Constraints: 1-1024 characters.
`claimValidationRules.cel.message`	Technology Preview. Error message displayed when validation fails. Constraints: 1-256 characters.
`claimValidationRules.requiredClaim`	Configures the required claim and value that the Kubernetes API server uses to validate if an incoming JWT is valid for this identity provider. Required when `type` is set to `RequiredClaim`.
`claimValidationRules.requiredClaim.claim`	Configures the name of the required claim. When taken from the JWT claims, the claim must be a string value. Must not be an empty string (`""`).
`claimValidationRules.requiredClaim.requiredValue`	Configures the value that `claim` must have when taken from the incoming JWT claims. If the value in the JWT claims does not match, the token is rejected for authentication. Must not be an empty string (`""`).
`claimValidationRules.type`	Validation rule type. Allowed values: `RequiredClaim` and `CEL`. `RequiredClaim` - Validates that the JWT contains the required claim with the required value `CEL` (Technology Preview) - Validates the JWT against a CEL expression
`issuer`	A required field that configures how the platform interacts with the identity provider and how tokens issued from the identity provider are evaluated by the Kubernetes API server.
`issuer.audiences`	A required field that configures the acceptable audiences the JWT token, issued by the identity provider, must be issued to. At least one of the entries must match the `aud` claim in the JWT token. Must contain at least one entry and must not exceed 10 entries.
`issuer.discoveryURL`	Optional parameter (Technology Preview). Custom OIDC discovery endpoint URL. Must be a valid HTTPS URL and differ from `issuer.issuerURL`. When not specified, Red Hat OpenShift Container Platform constructs the discovery URL by using the standard OIDC format: `{issuerURL}/.well-known/openid-configuration`.
`issuer.issuerCertificateAuthority`	Configures the certificate authority, used by the Kubernetes API server, to validate the connection to the identity provider when fetching discovery information. When not specified, the system trust is used. When specified, it must reference a config map in the `openshift-config` namespace containing the PEM-encoded CA certificates under the `ca-bundle.crt` key in the `data` field of the config map.
`issuer.issuerCertificateAuthority.name`	The name of the referenced config map.
`issuer.issuerURL`	Configures the URL used to issue tokens by the identity provider. The Kubernetes API server determines how authentication tokens should be handled by matching the `iss` claim in the JWT to the issuerURL of configured identity providers. This field is required and must use the `https://` scheme.
`name`	A required field that configures the unique human-readable identifier associated with the identity provider. It is used to distinguish between multiple identity providers and has no impact on token validation or authentication mechanics. Must not be an empty string (`""`).
`oidcClients`	Configures how on-cluster, platform clients should request tokens from the identity provider. Must not exceed 20 entries and entries must have unique namespace/name pairs.
`oidcClients.clientID`	Configures the client identifier, from the identity provider, that the platform component uses for authentication requests made to the identity provider. The identity provider must accept this identifier for platform components to be able to use the identity provider as an authentication mode. Must not be an empty string (`""`).
`oidcClients.clientSecret`	Configures the client secret used by the platform component when making authentication requests to the identity provider. When not specified, no client secret is used when making authentication requests to the identity provider. When specified, it references a secret in the `openshift-config` namespace that contains the client secret in the `clientSecret` key of the `.data` field. The client secret is used when making authentication requests to the identity provider. Public clients do not require a client secret, but private clients do require a client secret to work with the identity provider.
`oidcClients.clientSecret.name`	The name of the referenced secret.
`oidcClients.componentName`	Specifies the name of the platform component being configured to use the identity provider as an authentication mode. It is used in combination with `componentNamespace` as a unique identifier. Must not be an empty string (`""`) and must not exceed 256 characters in length.
`oidcClients.componentNamespace`	Specifies the namespace in which the platform component being configured to use the identity provider as an authentication mode is running. It is used in combination with `componentName` as a unique identifier. Must not be an empty string (`""`) and must not exceed 63 characters in length.
`oidcClients.extraScopes`	Configures the extra scopes that should be requested by the platform component when making authentication requests to the identity provider. This is useful if you have configured claim mappings that require specific scopes to be requested beyond the standard OIDC scopes. When omitted, no additional scopes are requested.
`userValidationRules`	Optional parameter (Technology Preview). Validation rules for user objects created from authenticated tokens. All rules must pass (AND operation). Each rule contains `expression` (must evaluate to `true`) and `message` (error text). Access user by using the `user` variable: `user.username` (string), `user.groups` (array), `user.uid` (string), `user.extra` (map).
`userValidationRules[].expression`	Required. CEL expression that validates the user object. Must evaluate to `true` for authentication to succeed. Constraints: 1-1024 characters, boolean result.
`userValidationRules[].message`	Required. Error message displayed when validation fails.

Example OIDC provider configuration for CLI clients only

In Red Hat OpenShift Container Platform clusters where the web console is disabled, you can configure direct authentication with an external OIDC provider for a CLI client only. In these cases, users must authenticate with the cluster directly through the OpenShift CLI (oc) instead of through the web console.

The following example OIDC provider configuration shows how to configure a CLI client without defining a web console client:

OIDC provider configuration with only a CLI client

apiVersion: config.openshift.io/v1
kind: Authentication
metadata:
# ...
spec:
  type: OIDC
  webhookTokenAuthenticator: null
  oidcProviders:
  - claimMappings:
      groups:
        claim: groups
        prefix: 'oidc-groups-test:'
      username:
        claim: email
        prefixPolicy: Prefix
        prefix:
          prefixString: 'oidc-user-test:'
    issuer:
      audiences:
      - my-cli-client-id
      issuerURL: my-issuer-url
    name: my-oidc-provider-name