Enabling direct authentication with an external OIDC identity provider
Esc
Start typing to search...
On this page

Enabling direct authentication with an external OIDC identity provider

Configure OpenShift Container Platform to use an external OpenID Connect (OIDC) identity provider directly for token-based authentication, replacing the built-in OAuth server with your organization’s existing identity infrastructure.

About direct authentication with an external OIDC identity provider

You can enable direct integration with an external OpenID Connect (OIDC) identity provider to issue tokens for authentication. This bypasses the built-in OAuth server and uses the external identity provider directly.

By integrating directly with an external OIDC provider, you can leverage the advanced capabilities of your preferred OIDC provider instead of being limited by the capabilities of the built-in OAuth server. Your organization can manage users and groups from a single interface, while also streamlining authentication across multiple clusters and in hybrid environments. You can also integrate with existing tools and solutions.

Important

Currently, you may configure only one OIDC provider for direct authentication.

After switching to direct authentication, existing authentication configuration is not guaranteed to be preserved. Before enabling direct authentication, back up any existing user, group, oauthclient, or identity provider configuration in case you need to revert back to using the built-in OAuth server for authentication.

Before replacing the built-in OAuth server with an external provider, ensure that you have access to a long-lived method of logging in with cluster administrator permissions, such as one of the following:

  • a certificate-based user kubeconfig file, such as the one generated by the installation program
  • a long-lived service account token kubeconfig file
  • a certificate-based service account kubeconfig file

If there are any issues with the external identity provider, you need one of these methods to gain access to the OpenShift Container Platform cluster in an emergency situation.

Disabled OAuth resources

When you enable direct authentication, several OAuth resources are intentionally removed.

Important

Ensure that you do not rely on these removed resources before configuring direct authentication.

The following resources are unavailable when direct authentication is configured:

  • OpenShift OAuth server and OpenShift OAuth API server
  • User and group APIs (*.user.openshift.io)
  • OAuth APIs (*.oauth.openshift.io)
  • OAuth server and client configurations

Direct authentication identity providers

Direct authentication has been tested with multiple OpenID Connect (OIDC) identity providers to help you verify compatibility before configuring your cluster.

The following identity providers have been tested:

  • Active Directory Federation Services for Windows Server
  • GitLab
  • Google
  • Keycloak
  • Microsoft Entra ID
  • Okta
  • Ping Identity
  • Red Hat Single Sign-On
Note

Red Hat does not test all factors associated with third-party identity provider functionality.

Additional resources

Configuring an external OIDC identity provider for direct authentication

Configure 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 OpenShift Container Platform web console enabled on the cluster.
    Note

    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

  1. 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.
  2. Create a secret that allows you to authenticate with the web console by running the following command:
    terminal
    $ 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.

  3. Optional: Create a config map that contains the provider’s certificate authority bundle by running the following command:
    terminal
    $ 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.

  4. Edit the authentication configuration by running the following command:
    terminal
    $ oc edit authentication.config/cluster
  5. 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:
    yaml
    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 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.

  6. Exit and save the changes to apply the new configuration.
  7. 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:
      terminal
      $ 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

  1. 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:
      terminal
      $ 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:

      terminal
      Logged into "https://api.my-cluster.example.com:6443" as "oidc-user-test:user1@example.com" from an external oidc issuer.
  2. Verify that you can log in to the 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 OpenShift Container Platform web console.

Additional resources

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:

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, <code>, </code>three<code>] becomes [</code>one<code>, </code>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, 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 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

Disabling direct authentication

Disable direct authentication to revert your cluster back to using the built-in OpenShift Container Platform OAuth server for authentication when external OIDC integration is no longer needed.

Prerequisites

  • You have access to the kubeconfig file generated by the installation program for the cluster.

Procedure

  1. 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.
  2. Update the authentication configuration to use the built-in OpenShift Container Platform OAuth server by running the following command:
    terminal
    $ oc patch authentication.config/cluster --type=merge -p='
spec:
  type: ""
  oidcProviders: null
'

    where:

    spec.type

    Specifies the authentication type. Set to "" to use the built-in OpenShift Container Platform OAuth server. A value of IntegratedOAuth is also equivalent.

    spec.oidcProviders

    Specifies the OIDC provider configuration. Set to null to remove the external OIDC provider configuration.

  3. 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:
      terminal
      $ 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 12; 1 node is at revision 14

      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.
  4. If necessary, restore any existing authentication configuration.

Verification

  • Verify that you can successfully log in to the OpenShift Container Platform web console and OpenShift CLI (oc).