Architecture Overview

This section introduces OpenShift External Authentication: what it is, why it matters, how it works, and how to choose the appropriate guide based on your environment.

Background

OpenShift has included an integrated OAuth server that has been central to managing access since the inception of OpenShift 3. This component enables the integration with a variety of external identity providers and issues access tokens that can be used to communicate with the platform.

While this capability has served enterprise organizations well, it represents a departure from how Kubernetes has evolved to handle authentication. This divergence has created compatibility challenges for organizations seeking to align security practices across their Kubernetes environments.

OpenShift External Authentication addresses this by allowing externally issued OIDC tokens to be used directly with the OpenShift API and Web Console — the same approach used in standard Kubernetes environments.

Benefits

Standardized workflows — Align OpenShift access with standard Kubernetes authentication patterns for immediate operational familiarity.
Tooling compatibility — The oc and kubectl CLIs work natively with external tokens without extra translation layers.
Unified governance — Centralize how identities are managed within a single provider across the entire hybrid fleet.
Hybrid alignment — Ensure consistent security practices across diverse, multi-vendor Kubernetes environments.
Provider flexibility — Supports any identity provider supporting the OIDC protocol; The Red Hat Build of Keycloak is used as the reference implementation within this guide to demonstrate the integration and introduce relevant security related concepts.

Components

The following components are involved in this reference architecture:

Red Hat OpenShift: The target environment supporting the external authentication capability. Externally generated OIDC tokens can be used to access the OpenShift API, including the kubectl and oc CLIs, as well as the OpenShift Web Console.
External authentication provider: The entity responsible for managing identity records and exposing integrations using the OIDC protocol.
Red Hat Build of Keycloak (RHBK): The reference implementation acting as the external authentication provider in this guide. See the RHBK documentation for installation steps. Configuration steps specific to this reference architecture are documented in the Red Hat Build of Keycloak Configuration section.
Break glass credential (managed OpenShift only): A temporary kubeconfig with cluster-admin privileges, available in ROSA HCP environments with external authentication enabled. Because there is no built-in administrator account when external authentication is active within ROSA HCP, break glass credentials provide a short-lived path (maximum 24 hours) for bootstrap tasks, such as assigning RBAC policies.

Authentication flow

The following sequence describes how a user authenticates to OpenShift using an external provider:

The user runs an OpenShift CLI command (for example, oc get pods).
The CLI contacts the external authentication provider (RHBK) using OIDC.
RHBK issues an ID token to the CLI.
The CLI presents the ID token to the OpenShift API.
OpenShift validates the token against the configured external provider.
Access is granted and the command result is returned.

Supported OpenShift Cluster Types

OpenShift External Authentication is available within the following OpenShift cluster types:

Cluster Type Status Notes

Cluster Type	Status	Notes
ROSA with Hosted Control Planes (HCP)	Generally Available	External authentication must be enabled at cluster creation time using the `--external-auth-providers-enabled` flag. Existing clusters cannot be migrated.
Azure Red Hat OpenShift (ARO) HCP^	Under active development	Steps and commands may change as the feature moves toward GA. External authentication is the only access method for ARO HCP clusters.
Self-Managed OpenShift 4.20+	Generally Available (4.20+) / Tech Preview (4.19)	On 4.19, the `TechPreviewNoUpgrade` feature set must be enabled — this permanently prevents cluster upgrades. Generally Available on 4.20 and later.

ROSA with Hosted Control Planes (HCP)

Generally Available

External authentication must be enabled at cluster creation time using the --external-auth-providers-enabled flag. Existing clusters cannot be migrated.

Azure Red Hat OpenShift (ARO) HCP^

Under active development

Steps and commands may change as the feature moves toward GA. External authentication is the only access method for ARO HCP clusters.

Self-Managed OpenShift 4.20+

Generally Available (4.20+) / Tech Preview (4.19)

On 4.19, the TechPreviewNoUpgrade feature set must be enabled — this permanently prevents cluster upgrades. Generally Available on 4.20 and later.

OpenShift Cluster Type Specific Guides

Select one of the following guides based on the target OpenShift environment:

ROSA HCP — Follow ROSA HCP for the steps to configure external authentication within ROSA HCP.
ARO HCP — Follow ARO HCP for the steps to configure external authentication within ARO HCP.
Self-managed OpenShift — Follow Self-Managed OpenShift for the steps to configure external authentication within Self-Managed OpenShift environments.

All three guides converge on Accessing OpenShift with External Credentials which describes how to use the OpenShift CLI and Web Console with clusters with External Authentication enabled.