Self-Managed OpenShift

This section describes the steps for integrating a self-managed OpenShift environment with an external authentication provider. The reference implementation uses Red Hat Build of Keycloak as the identity provider.

External Authentication is Generally Available (GA) on OpenShift 4.20 and later. On OpenShift 4.19, it is available as a Technology Preview feature that requires enabling the TechPreviewNoUpgrade feature set. Once this setting is enabled, the cluster can no longer be upgraded and the flag cannot be reverted. See the OpenShift documentation for additional information.

At a high level, the following steps are involved for OpenShift 4.19:

Enable the TechPreviewNoUpgrade feature set (OpenShift 4.19 only).
Assign OpenShift RBAC policies before enabling external authentication.
Create the OpenShift Console client secret.
(Optional) Configure CA trust for non-public TLS certificates.
Update the Authentication custom resource to enable external authentication.
Verify the configuration is active.

For OpenShift 4.20 and later, step 1 is not required.

Prerequisites

Assumptions

This guide does not cover installation of OpenShift or Red Hat Build of Keycloak. It assumes the user has cluster-admin rights and is already authenticated to the target cluster using the OpenShift CLI.

Consult the following documentation for additional information:

Required tools

The following utilities must be installed and configured on your local machine:

oc — OpenShift Command Line Interface (authenticated with cluster-admin rights)
jq — JSON command-line parser

External authentication provider

An external authentication provider must be available and accessible from the OpenShift cluster. See Red Hat Build of Keycloak Configuration for the reference implementation setup steps.

OpenShift API URL

Set the OpenShift API URL environment variable:

export OPENSHIFT_API_URL=$(oc whoami --show-server)

Set the RHBK host URL:

export RHBK_HOST=<rhbk_host>

Step 1: Enable the TechPreviewNoUpgrade feature set (OpenShift 4.19 only)

Enabling TechPreviewNoUpgrade permanently prevents the cluster from being upgraded and cannot be reverted. Skip this step on OpenShift 4.20 and later.

Enable the feature set:

oc patch featuregate cluster --type=merge --patch '{"spec": {"featureSet": "TechPreviewNoUpgrade"}}'

Confirm that the ExternalOIDC feature gate is enabled:

oc get featuregate cluster -o json | jq -r '.status.featureGates[0].enabled[] | select(.name == "ExternalOIDC") | length > 0'

A response of true confirms that the cluster is eligible to use the External Authentication feature.

Step 2: Assign RBAC policies

RBAC policies must be assigned before enabling external authentication. Once external authentication is enabled, the built-in OpenShift OAuth server is disabled and access to the cluster is only possible via OIDC credentials. Assigning RBAC policies first ensures that external users have access immediately after enabling external authentication.

Use a certificate-based authentication method (such as the cluster-admin kubeconfig generated at install time) for this step.

A common approach is to grant cluster-admin access to members of the openshift_admins group in the external provider:

oc apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: openshift-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: openshift_admins
EOF

Additional policies can be created as needed for other roles and groups.

Step 3: Create the OpenShift Console client secret

Create an OpenShift Secret in the openshift-config namespace containing the RHBK client secret for the OpenShift Console. This allows the OpenShift Web Console to use the confidential OIDC client.

Locate the client secret in RHBK:

In the openshift realm, select Clients in the left navigation bar.
Select openshift-console.
Select the Credentials tab.
The secret is in the Client Secrets section.

Create the secret:

oc create secret generic external-auth-console-secret \
    --from-literal=clientSecret=<secret_value> \
    -n openshift-config

Step 4: (Optional) Configure CA trust for non-public TLS certificates

If the external authentication provider uses a non-public TLS certificate, configure certificate trust in OpenShift by creating a ConfigMap in the openshift-config namespace.

oc create configmap external-auth-ca \
  --from-file=ca-bundle.crt=ca-bundle.crt \
  -n openshift-config

If the external authentication provider uses a certificate already trusted by OpenShift, this step may be omitted.

Step 5: Configure the Authentication custom resource

Before proceeding with this step, ensure a certificate-based authentication method (such as the install-time cluster-admin kubeconfig) is available and in use. Once external authentication is enabled, token-based and password-based authentication methods are no longer available.

The Authentication custom resource configures OpenShift to use an external OIDC provider. Setting spec.type to OIDC enables external authentication.

The following example shows the complete Authentication custom resource structure when using RHBK:

apiVersion: config.openshift.io/v1
kind: Authentication
metadata:
  name: cluster
spec:
  oidcProviders:
  - claimMappings:
      groups:
        claim: groups
        prefix: ''
      username:
        claim: preferred_username
        prefixPolicy: NoPrefix
    issuer:
      audiences:
        - openshift-console
        - openshift-cli
      issuerURL: $RHBK_HOST/realms/openshift
      # issuerCertificateAuthority:
      #   name: external-auth-ca  # Uncomment if using non-public TLS (Step 4)
    name: 'rhbk-external-auth'
    oidcClients:
      - clientID: openshift-cli
        componentName: cli
        componentNamespace: openshift-console
      - clientID: openshift-console
        clientSecret:
          name: external-auth-console-secret
        componentName: console
        componentNamespace: openshift-console
  type: OIDC
  webhookTokenAuthenticator: null

Key fields in this configuration:

claimMappings: Defines how username and group claims from the OIDC token are mapped to OpenShift identities. In the example above, the username uses the preferred_username claim and groups use the groups claim.
prefixPolicy: Controls whether a prefix is prepended to usernames from the external provider. NoPrefix maps the username directly. Using a prefix (for example, external-auth:) segregates external users from OpenShift’s local users.
audiences: List of valid audience values that must be present in the OIDC token. When using RHBK, the audience is set to the client name.
issuerCertificateAuthority: References the ConfigMap created in Step 4 if the provider uses a non-public TLS certificate.
oidcClients: References the OAuth clients configured in the external provider: one for the CLI and one for the Web Console.
clientSecret: For the openshift-console client, references the secret created in Step 3.
webhookTokenAuthenticator: Must be set to null when type is OIDC.

Apply the configuration:

oc patch authentication cluster --type="merge" -p "$(cat <<- EOF
spec:
  oidcProviders:
    - claimMappings:
        groups:
          claim: groups
          prefix: ''
        username:
          claim: preferred_username
          prefixPolicy: NoPrefix
      issuer:
        audiences:
          - openshift-console
          - openshift-cli
        issuerURL: $RHBK_HOST/realms/openshift
      name: 'rhbk-external-auth'
      oidcClients:
        - clientID: openshift-cli
          componentName: cli
          componentNamespace: openshift-console
        - clientID: openshift-console
          clientSecret:
            name: external-auth-console-secret
          componentName: console
          componentNamespace: openshift-console
  type: OIDC
  webhookTokenAuthenticator:
EOF
  )"

Step 6: Verify external authentication is enabled

After the Authentication custom resource is applied, a new revision of the Kubernetes API server rolls out to all control plane nodes. Monitor the rollout status:

oc get co kube-apiserver

When the AVAILABLE column shows True and both PROGRESSING and DEGRADED show False, external authentication is active on the cluster.

Next steps

With external authentication configured, users can now access the cluster using credentials from the external authentication provider.

See Accessing OpenShift with External Credentials for steps how to access the ROSA HCP cluster using CLI and Web Console.