Identity Configuration Management for Kubernetes and GitHub Authentication

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:

• Red Hat OpenShift Container Platform (RHOCP) 4.10, 4.9, or 4.8.12+ (due to BZ 1969902) for hub cluster

• RHACM 2.4 or Red Hat multicluster engine for Kubernetes (Technical Preview)

• Signed certificate used by RHOCP

  A signed certificate is required for the components used to authenticate the OpenID authentication requests. See the Security Requirements documentation.

  An easy way to do this is using letsencrypt and the instructions in the Add an ACME certificate section.

  NOTE: These instructions assume you have AWS access to allow proper registration of the certificate.

Install the Operator

From the OpenShift console, navigate to the OperatorHub page (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, and the following appears in the OpenShift console:

Select install, and take all the defaults to get identity configuration management for Kubernetes installed in the idp-mgmt-config namespace. Wait for the operator to install. After the installation completes, an IDPConfig must be created. This can be done using the Operator Hub page shown after the install completes:

Select Create IDP Config. Once installed, navigate to Operators > Installed Operator to verify the operator is installed:

Add a Managed Cluster

A managed cluster must be registered with the hub cluster. Use one of the various ways to do so. 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 appears. 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

A new namespace is used to contain the various custom resources. For example, run the following command from the command line:

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

Create a Cluster Set

A cluster set must be defined to determine the managed clusters that have the identity configuration changes applied. Use either the RHACM console or the command line. For example, run the following command from the command line:

echo '
apiVersion: cluster.open-cluster-management.io/v1beta1
kind: ManagedClusterSet
metadata:
  name: github-clusterset
  namespace: github-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: github-clusterset
  namespace: github-sample-ns
spec:
  clusterSet: github-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=github-clusterset --overwrite

Create a Placement Rule

Placement rules define what AuthRealm must be deployed to the managed clusters 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: github-placement
  namespace: github-sample-ns
spec:
  predicates:
  - requiredClusterSelector:
      labelSelector:
        matchLabels:
          authdeployment: east' | kubectl create -f -

Set Up the GitHub OAuth Application

For this example, set up OAuth authentication using GitHub:

1. Open a web browser, and navigate to GitHub. Go to Settings > Developer Settings > OAuth Apps, or use this link as a shortcut.

2. Add a New OAuth App. Copy the Client ID and Client Secret values. You will need these values later to set environment variables used by the generate-cr.sh script.

3. Fill in the Application name with something to help identify the owner and hub cluster it's used for.

   NOTE: If you have more than one hub cluster, each needs its own entry.

4. Fill in Homepage URL and Authorization callback URL with http://www.redhat.com.

   NOTE: A little later in this post, I explain how to correct the Homepage and Authorization callback URL value once the correct generated value is received.

5. Click Register Application.

   NOTE: You must return to the GitHub OAuth a little later to correct the Authorization callback URL after the value is generated for you. Therefore, leave this page open.

Add a New identity provider AuthRealm

Use the GitHub OAuth application information to create the secret and AuthRealm:

1. Create a GitHub secret needed by the AuthRealm. For example, run the following command:

   oc create secret generic github-client-secret -n  github-sample-ns --from-literal=clientSecret=<github-oauth-clientID-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: github
     namespace: github-sample-ns
   spec:
     type: dex
     routeSubDomain: testdomain
     placementRef:
       name: github-placement
     identityProviders:
       - name: "idpname"
         mappingMethod: add
         type: GitHub
         github:
           clientID: "<your GitHub OAth Application clientID name>"
           clientSecret:
             name: github-client-secret' | kubectl create -f -

Correct the GitHub OAuth Application Authorization Callback URL

With your AuthRealm created, you're ready to update your GitHub OAuth application authorization callback URL. Use this link as a shortcut. To generate the proper value, use the routeSubDomain specified in the AuthRealm, and run the following script while logged in to your hub cluster. For this example, change the routeSubDomain where the parameter value was set to testdomain:

export ROUTE_SUBDOMAIN=<your_route_subdomain>
export APPS=$(oc get infrastructure cluster -ojsonpath='{.status.apiServerURL}' | cut -d':' -f2 | sed 's/\/\/api/apps/g')
echo "Authorization callback URL: https://${ROUTE_SUBDOMAIN}.${APPS}/callback"

Label the Managed Cluster So It's 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 10 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. The new GitHub login option appears.

Log in using the GitHub option.

Additional Resources

• Identity configuration management for Kubernetes documentation

• Script to help generate example CRs

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

  export AUTHREALM_GITHUB_NAME=<AuthRelam name>
  export AUTHREALM_GITHUB_NS=<namespace to create resources>
  export IDP_NAME=<identity provider name>
  export GITHUB_APP_CLIENT_ID=<GitHub OAuth application client ID>
  export GITHUB_APP_CLIENT_SECRET=<GitHub OAuth application client secret>
  export ROUTE_SUBDOMAIN=<AuthRealm routeSubDomain>