Enabling direct authentication with an OIDC identity provider | Authentication and authorization

About direct authentication with an external OIDC identity provider
- Direct authentication identity providers
Configuring an external OIDC identity provider for direct authentication
- OIDC provider configuration parameters
Disabling direct authentication

While the built-in OpenShift OAuth server supports integration with a variety of identity providers, including external OpenID Connect (OIDC) identity providers, it is limited to the capabilities of the OAuth server itself. You can configure OKD to use an external OIDC identity provider directly to issue tokens for authentication, which replaces the built-in OpenShift OAuth server.

Direct authentication with an OIDC identity provider is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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.

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. Prior to 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 OKD cluster in an emergency situation.

Direct authentication identity providers

Direct authentication has been tested with the following OpenID Connect (OIDC) identity providers:

Keycloak
Microsoft Entra ID

Red Hat does not test all factors associated with third-party identity provider functionality. For more information about third-party support, see the Red Hat third-party support policy.

Configuring an external OIDC identity provider for direct authentication

You can configure OKD to directly use an external OIDC identity provider to issue tokens for authentication.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Prerequisites

You have enabled the TechPreviewNoUpgrade feature set.
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.

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> \(1)
    -n openshift-config
```
1 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 \(1)
    -n openshift-config
```
1 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:
  oidcProviders: (1)
  - claimMappings:
      groups:
        claim: groups (2)
        prefix: 'oidc-groups-test:'
      username:
        claim: email (3)
        prefixPolicy: Prefix
        prefix:
          prefixString: 'oidc-user-test:'
    issuer:
      audiences: (4)
      - console-test
      - oc-cli-test
      issuerCertificateAuthority:
        name: keycloak-oidc-ca (5)
      issuerURL: https://keycloak-keycloak.apps.example.com/realms/master (6)
    name: 'keycloak-oidc-server' (7)
    oidcClients:
    - clientID: oc-cli-test (8)
      componentName: cli
      componentNamespace: openshift-console
    - clientID: console-test (9)
      clientSecret:
        name: console-secret (10)
      componentName: console
      componentNamespace: openshift-console
  type: OIDC (11)
  webhookTokenAuthenticator: null (12)

1	The OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.
2	The name of the claim to construct group names for the cluster identity.
3	The name of the claim to construct usernames for the cluster identity.
4	The list of audiences that this authentication provider issues tokens for.
5	The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
6	The URL for the token issuer.
7	The name for external OIDC provider.
8	The client ID that your provider uses for the OpenShift CLI (`oc`).
9	The client ID that your provider uses for the OKD web console.
10	The name of the secret that stores the secret value for the console client.
11	Must be set to `OIDC` to indicate to use an external OIDC identity provider.
12	Must be set to `null` when `type` is set to `OIDC`.

For more details on all available parameters, see "OIDC provider configuration parameters".

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.19.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:

$ oc login --exec-plugin=oc-oidc \(1)
    --issuer-url=https://keycloak-keycloak.apps.example.com/realms/master \(2)
    --client-id=oc-cli-test \(3)
    --extra-scopes=email --callback-port=8080 \
    --oidc-certificate-authority my-directory/ca-bundle.crt (4)

1	Specify `oc-oidc` as the exec plugin type. Only a value of `oc-oidc` is allowed.
2	Specify the issuer URL for your identity provider.
3	Specify client ID for the OpenShift CLI (`oc`).
4	Specify 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

Open http://localhost:8080 in a browser.
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 OKD 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 OKD web console.

OIDC provider configuration parameters

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

Table 1. `oidcProviders` configuration
Parameter	Description
`claimMappings`	Configures the rules to be used by the Kubernetes API server for translating claims in a JWT token, issued by the identity provider, to a cluster identity.
`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`	Configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.
`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.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`	Configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.
`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.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.
`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`	Configures the type of the validation rule. Allowed values are `RequiredClaim` and omitted (not provided or an empty string). When set to `RequiredClaim`, the Kubernetes API server is configured to validate that the incoming JWT contains the required claim and that its value matches the required value. The default value is `RequiredClaim`.
`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.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.

Disabling direct authentication

If necessary, you can disable direct authentication for your cluster and revert back to authenticating with the built-in OpenShift OAuth server.