Accessing OpenShift with External Credentials

Once an OpenShift environment has been configured with external authentication, the cluster is accessible using credentials from the external authentication provider via the OpenShift CLI or the Web Console.

This section describes the supported access methods across all three cluster types covered in this reference architecture.

OpenShift CLI access

Three methods are available for accessing an OpenShift cluster using OIDC tokens from an external provider:

Included OpenShift CLI functionality — Use the oc-oidc exec plugin with oc login.
Manual OIDC token — Manually obtain an OIDC token and configure kubectl credentials using the OIDC auth provider.
client-go Credential Plugin — Use a credential plugin to automate OIDC token management.

Each method requires authenticating to the external provider first to obtain an OIDC token. When using the reference RHBK instance, the openshift-cli OAuth client is used.

Method 1: Included OpenShift CLI functionality

Recent versions of the OpenShift CLI support authenticating to a cluster configured with external authentication using the oc-oidc exec plugin.

The following values are required:

The hostname of the RHBK instance
The OAuth Client ID (openshift-cli)
The Client Secret of the RHBK client if configured as a confidential client
The OpenShift API URL

The oc login command takes the following form:

oc login \
    --client-id=<client_id> \
    --exec-plugin=oc-oidc \
    --issuer-url=<issuer_url> \
    <openshift_api_url>

Use --client-secret=<client_secret> if the RHBK client was configured as a confidential client.

Authenticate using the RHBK reference implementation:

oc login \
    --client-id=openshift-cli \
    --exec-plugin=oc-oidc \
    --issuer-url=$RHBK_HOST/realms/openshift \
    $OPENSHIFT_API_URL

After running this command, a browser URL is printed:

Please visit the following URL in your browser: http://localhost:<random_port>

Open the URL in a browser, complete authentication using the external provider credentials, and the CLI will log in to the OpenShift cluster.

Verifying the identity

Confirm that the OIDC identity is being used:

oc auth whoami

Expected output:

ATTRIBUTE                                           VALUE
Username                                            openshift_admin
Groups                                              [openshift_admins system:authenticated]
Extra: authentication.kubernetes.io/credential-id   [JTI=<JTI>]

Confirm the username matches the expected user and that group membership is mapped correctly.

Confirm that RBAC policies are in effect:

oc get clusteroperators

A successful response confirms that the cluster-admin ClusterRoleBinding applied for the openshift_admins group is working correctly.

Method 2: Manual OIDC token

An OIDC token can be obtained manually from the external provider and used to configure OpenShift CLI credentials directly.

This method requires enabling the Direct access grants (Resource Owner Password Credentials) flow in the RHBK client. This is less secure than device authorization flows and is intended for testing or automation scenarios.

Enable direct access grants in RHBK:

In the openshift realm, select Clients and select openshift-cli.
On the Settings tab, under Capability config, enable Direct access grants.
Click Save.

Obtain an OIDC token using curl:

RHBK_TOKEN=$(curl -s -X POST \
    $RHBK_HOST/realms/openshift/protocol/openid-connect/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d scope=openid \
    -d username=openshift_admin \
    -d password=<password> \
    -d grant_type=password \
    -d client_id=openshift-cli)

Include -d client_secret=<client_secret> if the RHBK client was configured as a confidential client.

Configure a new OIDC credential for the OpenShift CLI:

oc config set-credentials rhbk-oidc-provider \
  --auth-provider=oidc \
  --auth-provider-arg=idp-issuer-url=$RHBK_HOST/realms/openshift \
  --auth-provider-arg=client-id=openshift-cli \
  --auth-provider-arg=refresh-token=$(echo $RHBK_TOKEN | jq -r '.refresh_token') \
  --auth-provider-arg=id-token=$(echo $RHBK_TOKEN | jq -r '.id_token')

Create an OpenShift CLI context using the new credential:

oc config set-context openshift-external-auth \
  --cluster=$(oc config view -o json | jq -r --arg CURRENT_CONTEXT $(oc config view -o json | jq -r '."current-context"') '.contexts[] | select(.name == $CURRENT_CONTEXT).context.cluster') \
  --namespace=default \
  --user=rhbk-oidc-provider

Set the new context as current:

oc config use-context openshift-external-auth

Verify the identity:

oc auth whoami

Method 3: client-go Credential Plugin

A client-go Credential Plugin is a separate binary that integrates with the OpenShift CLI to obtain and manage OIDC tokens automatically.

The plugin binary must:

Have a name prefixed with kubectl-
Be located in a directory on the system PATH

The oidc-login plugin is used in this reference architecture. Install it using one of the supported installation methods.

Configure a kubectl credential that uses the oidc-login plugin:

oc config set-credentials rhbk-oidc-login \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=$RHBK_HOST/realms/openshift \
  --exec-arg=--oidc-client-id=openshift-cli

Include --exec-arg=--oidc-client-secret=<client_secret> if the RHBK client was configured as a confidential client.

Create or update an OpenShift CLI context that uses the new credential:

oc config set-context openshift-external-auth \
  --cluster=$(oc config view -o json | jq -r --arg CURRENT_CONTEXT $(oc config view -o json | jq -r '."current-context"') '.contexts[] | select(.name == $CURRENT_CONTEXT).context.cluster') \
  --namespace=default \
  --user=rhbk-oidc-login

Set the new context as current:

oc config use-context openshift-external-auth

Verify the identity:

oc auth whoami

When this command runs, the oidc-login plugin launches a browser window for authentication with the external provider. After successful login, the OIDC token is stored for subsequent invocations.

Expected output:

ATTRIBUTE                                           VALUE
Username                                            openshift_admin
Groups                                              [openshift_admins system:authenticated]
Extra: authentication.kubernetes.io/credential-id   [JTI=<JTI>]

OpenShift Web Console access

OIDC tokens provided by an external authentication provider can also be used with the OpenShift Web Console.

Retrieve the Web Console URL for your environment:

Environment Command

Environment	Command
Self-managed OpenShift	`echo $(oc whoami --show-console)`
ROSA HCP	`echo $(rosa describe cluster -c $ROSA_CLUSTER_NAME -o json \| jq -r '.console.url')`
ARO HCP	`echo $(az rest --method GET --uri "/subscriptions/${ARO_SUBSCRIPTION_ID}/resourceGroups/${ARO_RESOURCE_GROUP}/providers/Microsoft.RedHatOpenShift/hcpOpenShiftClusters/${ARO_CLUSTER_NAME}?api-version=2024-06-10-preview" \| jq -r '.properties.console.url')`

Self-managed OpenShift

echo $(oc whoami --show-console)

ROSA HCP

echo $(rosa describe cluster -c $ROSA_CLUSTER_NAME -o json | jq -r '.console.url')

ARO HCP

echo $(az rest --method GET --uri "/subscriptions/${ARO_SUBSCRIPTION_ID}/resourceGroups/${ARO_RESOURCE_GROUP}/providers/Microsoft.RedHatOpenShift/hcpOpenShiftClusters/${ARO_CLUSTER_NAME}?api-version=2024-06-10-preview" | jq -r '.properties.console.url')

Navigate to the URL in a browser. The OpenShift Web Console redirects to the external authentication provider. Authenticate using the configured user credentials. After a successful login, the browser redirects back to the OpenShift Console.

Confirm that the correct username appears in the top-right corner of the page and that the user has the expected level of access based on the configured RBAC policies.