ROSA with Hosted Control Planes (HCP)

This section describes the steps for deploying and integrating a ROSA Hosted Control Planes (HCP) environment with an external authentication provider. The reference implementation uses Red Hat Build of Keycloak as the identity provider.

At a high level, the following steps are involved:

  1. Deploy a ROSA HCP cluster with external authentication provider support enabled.

  2. Create an external authentication provider on the cluster.

  3. Create a break glass credential to access the cluster.

  4. Authenticate using the break glass credential.

  5. Assign OpenShift RBAC policies to external identities.

  6. Revoke the break glass credential.

  7. Authenticate using credentials from the external authentication provider.

Prerequisites

Assumptions

This guide does not cover installation of ROSA HCP (outside of the steps required to enable external authentication) or installation of Red Hat Build of Keycloak as the reference identity provider. It assumes the user has the appropriate permissions to complete the described tasks.

Consult the following documentation for additional information:

Required tools

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

  • rosa — ROSA Command Line Interface

  • oc — OpenShift Command Line Interface

  • jq — JSON command-line parser

External authentication provider

An external authentication provider must be available and accessible from the ROSA cluster before beginning. If you do not already have one configured, see Red Hat Build of Keycloak Configuration for the reference implementation setup steps.

Cluster deployment

External authentication support must be enabled at cluster creation. Existing clusters cannot be upgraded or changed to support external authentication.

Set the ROSA cluster name:

export ROSA_CLUSTER_NAME=<rosa_cluster_name>

Set the OpenShift API URL:

export OPENSHIFT_API_URL=$(rosa describe cluster -c $ROSA_CLUSTER_NAME -o json | jq -r '.api.url')

Create a new ROSA HCP cluster with external authentication provider support enabled:

rosa create cluster --hosted-cp --cluster-name=$ROSA_CLUSTER_NAME \
   --external-auth-providers-enabled \
   <additional_flags>
Consult the official ROSA documentation for the full set of required flags. The --create-admin-user flag cannot be used with external authentication; use a break glass credential instead.

After the cluster is created, verify that external authentication support is enabled:

rosa describe cluster -c $ROSA_CLUSTER_NAME -o json | jq -r '.external_auth_config.enabled'

A response of true confirms that external authentication is enabled.

Adding an external authentication provider

Once the ROSA cluster is created, add an external authentication provider to configure the cluster to accept OIDC tokens from that provider.

Requirements

  • The external authentication provider must be network-accessible from the ROSA cluster.

  • One or more OAuth clients must be configured in the provider for use by OpenShift:

OpenShift Component Required Redirect URI

OpenShift API

Implementation-specific

OpenShift Web Console

https://<console_host>/auth/callback

Command reference

The rosa create external-auth-provider command accepts the following flags:

Flag Description

--cluster

Name of the ROSA cluster

--name

Name to associate with the external authentication provider

--issuer-url

URL of the external authentication provider (issuer URL of the RHBK realm)

--issuer-audiences

Comma-separated list of valid OIDC token audience values

--claim-mapping-username-claim

Claim in the OIDC token that contains the username

--claim-mapping-groups-claim

Claim in the OIDC token that contains group membership

--console-client-id

OAuth Client ID for the OpenShift Web Console

--console-client-secret

OAuth Client Secret for the OpenShift Web Console (optional but recommended)
The first value in --issuer-audiences must be the OIDC Client ID associated with the OpenShift Web Console.

Locating the required values from RHBK

Issuer URL

  1. In the openshift realm, select Realm settings in the left navigation bar.

  2. Next to Endpoints, select the OpenID Endpoint Configuration link.

  3. The issuer field is the first property in the OIDC Discovery Document.

Issuer audiences

The issuer audiences is a comma-separated list of valid OIDC token audiences (aud claim). By default, RHBK sets the ID token audience to the name of the RHBK client (for example, openshift-cli).

The first value must be the OAuth Client ID for the OpenShift Web Console (openshift-console).

Username claim

RHBK uses the preferred_username claim for the username in the OIDC token.

OpenShift Console client secret

Because the RHBK OAuth client for the OpenShift Console is configured as a confidential client, a client secret is generated:

  1. In the openshift realm, select Clients in the left navigation bar.

  2. Select openshift-console.

  3. Select the Credentials tab.

  4. The secret is in the Client Secrets section.

Adding the provider using RHBK

Set the RHBK host URL:

export RHBK_HOST=<rhbk_host>

Add the external authentication provider to the ROSA HCP cluster:

rosa create external-auth-provider --cluster=$ROSA_CLUSTER_NAME \
    --name=rhbk  \
    --issuer-url=$RHBK_HOST/realms/openshift \
    --issuer-audiences=openshift-console,openshift-cli \
    --claim-mapping-username-claim=preferred_username \
    --claim-mapping-groups-claim=groups \
    --console-client-id=openshift-console \
    --console-client-secret=<openshift_console_client_secret>
After the external authentication provider is created, it may take several minutes to become active on the cluster.

Break glass credentials

A main difference between a standard ROSA HCP cluster and one with external authentication enabled is that there is no built-in administrator account. Break glass credentials provide temporary cluster-admin access (maximum 24 hours) for bootstrap tasks such as assigning RBAC policies.

Creating a break glass credential

rosa create break-glass-credential -c $ROSA_CLUSTER_NAME --username=breakglass
The --username flag is optional. Providing a value makes it easier to manage the generated kubeconfig.

Retrieving the credential

Get the ID of the newly created credential:

export ROSA_BREAK_GLASS_CREDENTIAL_ID=$(rosa list break-glass-credential -c $ROSA_CLUSTER_NAME -o json | jq -r '[.[] | select(.status=="issued")][0].id')

Download the kubeconfig file:

rosa describe break-glass-credential $ROSA_BREAK_GLASS_CREDENTIAL_ID -c $ROSA_CLUSTER_NAME --kubeconfig > rosa-cluster.kubeconfig

Using the credential

Set the KUBECONFIG environment variable so the OpenShift CLI uses the break glass credential:

export KUBECONFIG=$(pwd)/rosa-cluster.kubeconfig

Verify access with elevated privileges:

oc get clusteroperators

A successful response lists all cluster-level operators in the ROSA cluster.

Assigning RBAC policies

With the break glass credential active, assign OpenShift RBAC policies so that identities from the external authentication provider are granted the permissions they need. These policies persist after the break glass credential is revoked.

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 to support other roles and groups from the external authentication provider.

Removing the break glass credential

After completing bootstrap tasks, remove all traces of the break glass credential to prevent unintentional use of privileged access.

Revoke on the ROSA cluster

rosa revoke break-glass-credentials -c $ROSA_CLUSTER_NAME

Remove from the kubeconfig file

Remove the breakglass user entry from the kubeconfig file:

oc config delete-user breakglass
Ensure the KUBECONFIG environment variable points to the kubeconfig file that contains the break glass credential before running this command.

Next steps

With external authentication configured and RBAC policies applied, users can now access the ROSA 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.