Introduction

Identity configuration management for Kubernetes enhances the capabilities of Red Hat Advanced Cluster Management for Kubernetes (RHACM) or the multicluster engine for Kubernetes by enabling OpenShift administrators to define their identity provider configuration, once in the management hub cluster. Using simple placement rules, that same configuration can be used across multiple managed clusters within the fleet.

Prerequisites

Based on the full list of requirements, here are the most important ones to highlight:

Install the Keycloak community operator

From the OpenShift console, navigate to the OperatorHub page (select Operators > OperatorHub) and enter keycloak in the search box (it might take a few seconds for it to appear). Once the operator appears, select it. Your OpenShift console might resemble the following screen capture:

OperatorHubKeycloak

Select to install Keycloak and use all the defaults except the Installed namespace. From the OpenShift console click Select project > Create project > Name. Enter keycloak then click Create. Remember to install the Keycloak operator in the keycloak namespace. View the following image:

InstallKeycloakProject Wait for the operator to install:

KeycloakInstalled Log in to the OpenShift hub using the following command:

oc login

Verify that OpenShift is being used by checking the OpenShift URL. Run the following command:

oc cluster-info

Create a Keycloak instance

Now that the Keycloak operator is installed, create a Keycloak instance to be used for OpenID authentication. Define the following environment variable:

export KEYCLOAK_NAMESPACE=keycloak

Run the config-keycloak.sh helper script to create the Keycloak instance. It might take a few minutes to complete:

./config-keycloak.sh

Be sure to save the output of the script. Some of the generated values are needed in the future. In the output, find the value of OPENID_ISSUER and set an environment variable:

export OPENID_ISSUER="<openid issuer value from script output>"

In the output, find the value of OPENID_CLIENT_ID and OPENID_CLIENT_SECRET and set the environment variables:

export `OPENID_CLIENT_ID`="<openid client id value from script output>"
export `OPENID_CLIENT_SECRET`="<openid client secret value from script output>"

Install the identity configuration management for Kubernetes Operator

From the OpenShift console, navigate to the OperatorHub page (select Operators > OperatorHub) and enter identity in the search box (it might take a few seconds for it to appear). Once the operator appears, select it. The following content is shown from the OpenShift console:

OperatorHub Select Install and use all the default values to install identity configuration management for Kubernetes in the idp-mgmt-config namespace. Wait for the operator to install. After the installation completes, an IDPConfig needs to be created. This can be done using the Operator Hub page shown after the install completes:

CreateIDPConfig Select Create IDPConfig. Once installed, navigate to Operators > Installed Operator to verify the operator is installed. Your OpenShift console might resemble the following screen capture:

InstalledOperator

Add a managed cluster

A managed cluster must be registered with the hub cluster. Use one of the various ways available to get the managed cluster registered with the hub cluster. For this example, I use my managed cluster cahl-mc.

Once the managed cluster is registered, wait until the the managed cluster is JOINED and the MANAGED CLUSTER URL is shown. For example, use the command line to verify if the managed cluster cahl-mc is fully registered:

oc get managedclusters
NAME HUB ACCEPTED MANAGED CLUSTER URLS JOINED AVAILABLE AGE
cahl-mc true https://api.aws-4-9-sno-2x-rrt25.redhat.com:6443 True True 47h
local-cluster true https://api.aws-4-10-5-sno-2x-2zsqs.redhat.com:6443 True True 2d22h

Create a namespace

Create a new namespace to contain the various custom resources. For example, run the following command:

echo '
apiVersion: v1
kind: Namespace
metadata:
labels:
control-plane: controller-manager
name: openid-sample-ns' | kubectl create -f -

Create a cluster set

A cluster set must be defined to determine the managed clusters which have the identity configuration changes applied. Use either the RHACM console or the command line. For example, create a cluster set by using the following command:

echo '
apiVersion: cluster.open-cluster-management.io/v1beta1
kind: ManagedClusterSet
metadata:
name: openid-clusterset
namespace: openid-sample-ns' | kubectl create -f -

Bind the managed cluster to the cluster set

Use the following command to bind the managed cluster to the cluster set:

echo '
apiVersion: cluster.open-cluster-management.io/v1beta1
kind: ManagedClusterSetBinding
metadata:
name: openid-clusterset
namespace: openid-sample-ns
spec:
clusterSet: openid-clusterset' | kubectl create -f -

Label the managed cluster so it joins the cluster set

From the command line, run the following command:

oc label managedclusters cahl-mc cluster.open-cluster-management.io/clusterset=openid-clusterset --overwrite

Create a placement rule

Placement rules define what AuthRealm needs to be deployed to the managed clusters that are in the managed cluster set. For this example, a label is applied to the managed cluster to determine placement. For example, run the following command:

echo '
apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: Placement
metadata:
name: openid-placement
namespace: openid-sample-ns
spec:
predicates:
- requiredClusterSelector:
labelSelector:
matchLabels:
authdeployment: east' | kubectl create -f -

Add a new identity provider AuthRealm

Use the Keycloak OpenID information to create the secret and AuthRealm:

  1. Create an OpenID secret needed by the AuthRealm. For example, run the following command:

    oc create secret generic openid-openid-client-secret -n  openid-sample-ns --from-literal=clientSecret=${OPENID_CLIENT_SECRET}
  2. Create the AuthRealm. For example, run the following command using the command line:

    echo '
    apiVersion: identityconfig.identitatem.io/v1alpha1
    kind: AuthRealm
    metadata:
    name: openid
    namespace: openid-sample-ns
    spec:
    type: dex
    routeSubDomain: openid-subdomain
    placementRef:
    name: openid-placement
    identityProviders:
    - name: "openid"
    mappingMethod: add
    type: OpenID
    openID:
    clientID: "<your OPENID_CLIENT_ID value>"
    clientSecret:
    name: openid-openid-client-secret
    claims:
    preferredUsername:
    - preferred_username
    name:
    - name
    email:
    - email
    issuer: "<your OPENID_ISSUER value>"' | kubectl create -f -

Label the managed cluster so it is part of the placement

Run the following command to label the managed cluster:

oc label managedclusters cahl-mc authdeployment=east

Check the managed cluster identity configuration

Fairly soon after the label is added for your Placement, the managed cluster OAuth configuration is updated, usually less than ten seconds later. Once the OAuth configuration change is made, it may take up to 5 minutes for the various pods used for authetication on the managed cluster to restart and pick up the change.

Once the oauth-openshift pod in namespace openshift-authentication has restarted, log out of the managed cluster console and the new OpenID login option appears.

login-with-openid Log in using the OpenID option. The username and password can be found in the Keycloak User Info: section of output from the helper script config-keycloak.sh run previously.

Additional resources

  • Identity configuration management for Kubernetes documentation

  • Script used to setup Keycloak instance

    The Keycloak community operator needs to already be installed into the keycloak namespace before running this script.
    NOTE: The following environment variables must be defined for OpenID before using the generate-cr.sh script.

    export KEYCLOAK_NAMESPACE=keycloak
    export OPENID_ROUTE_SUBDOMAIN=openid-subdomain
  • Script to help generate example CRs

    NOTE: The following environment variables must be defined for OpenID before using the generate-cr.sh script.

    export AUTHREALM_OPENID_NAME=<AuthRelam name>
    export AUTHREALM_OPENID_NS=<namespace to create resources>
    export IDP_NAME=<identity provider name>
    export KEYCLOAK_NAMESPACE=keycloak
    export ROUTE_SUBDOMAIN=<AuthRealm routeSubDomain>
    export OPENID_CLIENT_ID=<output value shown by running hack/config-keycloak.sh>
    export OPENID_CLIENT_SECRET=<output value shown by running hack/config-keycloak.sh>
    export OPENID_ISSUER=<output value shown by running hack/config-keycloak.sh>
    export OPENID_ROUTE_SUBDOMAIN=openid-subdomain