In this article, we will walk through how to integrate Red Hat Single Sign-on (RH-SSO) with as an identity provider for authenticating against OpenShift clusters. This configuration will allow you to control user access to your OpenShift clusters through, a great tool for most government agencies.

A few notes before we begin

  • Red Hat Single Sign-on is based on the upstream project Keycloak.
  • Any reference to the name Keycloak can be substituted with RH-SSO for the purpose of this article.
  • For you must have the appropriate access to create “Project Applications” in their UI.
  • You will need cluster admin privileges to your OpenShift cluster in order to configure OAuth.

This walkthrough will include the basic setup of Red Hat Single Sign-on (RH-SSO) and a configuration on an existing OpenShift cluster. For a more in-depth look at RH-SSO, please check out: Adding authentication to your Kubernetes Web applications with Keycloak. For an OpenShift installation: OpenShift 4.x Installation - A Quick Overview.

First, we will need to set up a new account and application.

Set up account

In order to set up the appropriate access for, we went through the documentation and found that supports JSON Web Token `private_key_jwt` or Proof Key for Code Exchange by OAuth Public Clients `PKCE` for OpenID Connect (OIDC). Since the out-of-the-box authorization mechanism for OpenShift supports the OIDC implicit grant flow, RH-SSO is necessary for `private_key_jwt` validation.

Navigate to log in or create a new account.

After creating a account, navigate to and log in. This will redirect you to: where we will begin setting up the project application. Note, you will need to set up your own team or be provided one, which should look like this…


Create Test App

The Test app in allows an external provider (in our case, OpenShift) to communicate with in order to authenticate a user.

Once we have logged in to, we can create a new test application with: 


Click “Create a new test app” and that will lead us to…

Screen Shot 2021-03-17 at 3.02.07 PM

Name: [add your project name here]

        Team: [select your team from dropdown]

        Issuer: urn:gov:gsa:openidconnect.profiles:sp:sso:agency_name:app_name *

Return to App URL: **

Redirect URIs: **

        Attribute Bundle: Check “email”, “first_name”, “last_name”

        Active: Yes

Click Create/Update

* Note: please replace `agency_name` and `app_name`

** Note: please replace `` with your cluster name and domain.

We will come back to this page after we create RH-SSO to finish up a couple of edits.

Deploy Red Hat Single Sign-on on OpenShift

Next, we will deploy the Red Hat Single Sign-on Operator and configure it to use as a Client.

  • Login to OpenShift using credentials with cluster admin access
  • Create a new project for RH-SSO. In this example, the project is called security-operations* From the Administrator perspective, select Home -> Projects -> Create Project
  • Now, we will install the RH-SSO operator.
  • Navigate to Operators on the left panel, then click on OperatorHub, then Search for `SSO`. The following should appear:

*Note a few screenshots may say “secops”


Click the tile and you will be brought to this page.

Screen Shot 2021-02-23 at 1.10.17 PM

Click the Install button. This will redirect you to a screen below where we will configure and install the Red Hat Single Sign-on Operator into the security-operations namespace.

After you click “Install”, you can verify the operator was installed successfully by clicking the Installed Operators in the Left Panel under Operators.

Now that we have the operator installed, we will create an instance of Keycloak. If you are not familiar with Operators, please check out this Operators 101 from Alexandre Menezes on's blog.

If you click on `Red Hat Single Sign-On Operator` above it will take you to the following screen.

unnamed (1)-1

Here we will click “Create Instance”

Screen Shot 2021-03-19 at 2.17.38 PM

Keep all the defaults, scroll to the bottom and click “Create”

Screen Shot 2021-03-19 at 2.17.51 PM

Once we have created the instance, change to the Developer perspective, then select “Topology” and view our Keycloak instance running...

In order to integrate RH-SSO (this is our Keycloak instance we just created) with, we will need to configure a few more items.

Let’s find the admin password under Developer view and then click Secrets on the left panel.

We are looking for a secret called `credential-example-keycloak`.

Note: if you changed the name of your Keycloak instance during creation, your secret name might look slightly different, but should always begin in `credential`.

Click “Reveal Values” you can grab the Admin username and password.

Let’s grab the URL for RH-SSO so we can login.

Navigate to “Networking”, then “Routes” in the Administrator view under the “security-operations” project.

Screenshot from 2021-03-17 13-51-09

Under “Location” you will see a link. Click on that link, then click Administration Console.

Now, we can log into RH-SSO with the Admin username and password from above.

Once logged in, you should see a screen similar to the following...

For this initial exercise, we will be using the default Master Realm. From the Keycloak documentation:

A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.

Note: it is recommended to create another Realm for, especially if you wish to use multiple Identity Providers with this SSO.

Now, let’s add as an identity provider.

Create Identity Provider

On the left panel, navigate to “Identity Providers”, click the drop down “Add Providers…”, select “Open ID Connect v1.0”.

        Alias: login-gov

        Display Name:

        Enabled: On

        Stored Tokens Readable: On


        *Note: Display Name is the pretty name and what will appear on the SSO login page

Scroll down to the bottom...

Import from URL:

Then click Import.

A number of fields above should now be filled out in the OpenID Connect Config.

Let’s go back up to the top and edit the following fields:

*Note this came from what we specified in dashboard.

**We discovered there were the “ACR value errors” returning from While ACR values are not required by OIDC, will not function without passing them through. We solved this by looking at: and then taking and encode it to: so that we could add it on as URL parameters to the authorization URL.

***Validate Signatures is turned off because RH-SSO requires the use of “use” and “alg” for the JWKS URL provided by (, even though these keys are optional via It should be noted that “Use JWKS URL” can be turned off, but “If the switch is off, then public key (or certificate) from the Keycloak DB is used, so whenever the identity provider keypair changes, you will always need to import the new key to the Keycloak DB as well.” from

It should now look like this...

Screenshot from 2021-03-17 14-40-08

Click “Save”.

At this point, the configuration has allowed our Red Hat Single Sign-on to talk with We still need to allow RH-SSO to communicate with OpenShift to complete the full functionality.

Create KeycloakClient

Creating a client within our RH-SSO instance will allow us to connect the external Identity Provider,, with our OpenShift OAuth system. describes a client as:
Clients are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution.”

So our client, OpenShift, will request Keycloak authenticate a user against the Identity Provider,, that we configured in the previous step.

Let’s start by navigating to “Clients” on the left and clicking “Create” in the top right corner, which will redirect you to this page…

Click “Create” and you should see the following...

Here we will configure a few items to make sure OpenShift can talk with RH-SSO…

Access Type: Confidential

Standard Flow: On

Service Accounts Enabled: On

Authorization Enabled: On

Direct Access Grants: On

Valid Redirect URI*:* 

Click Save 

*Note: the Redirect URI comes from the “oauth-openshift” Route in the “openshift-authentication” project. This Route is an endpoint to allow Authentication against the cluster, and we provide it to Keycloak so it knows where to redirect after a user has been authenticated correctly against It is the internal OAuth mechanism for OpenShift. The OIDC route follows the well-defined route convention within OpenShift: 

Now navigate to the Credentials tab.

Here we want to copy the secret, it should look like a hash. We will use this is our OAuth setup for OpenShift.

Create OpenShift OAuth for Red Hat Single Sign-on

First, we need to grab the OpenShift cluster’s router-ca certificate. On the left panel, navigate to “Workloads”, then “Secrets”.

Make sure you are on the “openshift-ingress-operator” project and then search for “router-ca”. See below…

pasted image 0-4

Click on “router-ca”.

Screen Shot 2021-02-23 at 2.49.44 PM

Click on reveal to expose the content of the certificate. Then, copy `tls.crt` into a file on your local machine which will be uploaded to in the next step.

Note: if you have updated or changed your Router certificate, please make sure to use that certificate.

Now, configure the Identity Provider which is located under “Administration” on the left panel and then click on to “Cluster Settings”.

unnamed (2)-1

From the Cluster Settings page, select the “Global configuration” tab and then scroll down to “OAuth”.

Click “Add” then select “OpenID Connect”.

Enter the following information on the OpenID Connect Identity page.

Name: keycloak

ClientID: openshift *

Client secret: <from what we copied above in step __insert link___>

Issuer URL: **

CA file: click “Browse…” and upload the `tls.crt` we downloaded from `router-ca` in the step before.

Click Add.

* Note: Your Client ID here must match your RH-SSO Client ID we configured above.

** Note: please replace `` with your cluster name and domain. 

Note: While OpenShift provides additional mapping options of fields and usernames, only `preferred_username`, `name`, and `email` are available.

Add RH-SSO Certificate to

The last piece of necessary configuration is to add the Certificate that RH-SSO generates into they can communicate.

Let’s go back to the RH-SSO console and go to “Realm Settings” then go to the “Keys” tab.

Click on “Certificate” on the right, and copy the value. From here we’ll have to make a couple of small edits to make sure the format is correct for

To be PEM Encoded this certificate needs to have `-----BEGIN CERTIFICATE-----` on the first line and `-----END CERTIFICATE-----` on the last line, and a new line after exactly the 64th character. Here is an example...

Once we have this we need to head back over to our test app page and paste it into “Public Certificate”.

Click “Update”.

Verify and Conclusion

With the necessary configuration complete to integrate, RH-SSO and OpenShift, let’s verify that we can complete the authentication process. Logout of the cluster or open a Private browser so you have a clean session. You should see a screen presented similar to the following:

Within RH SSO, you will see your sign in on the right!

Click and it will redirect you to a page similar to the following: will now pass authentication back to your cluster and create your user if it does not exist.

Screenshot from 2021-03-18 14-41-11

Click Submit and you will be redirected to the OpenShift console.

Let’s recap. First, we configured for authentication against our OpenShift cluster and created Red Hat Single-Sign On through OperatorHub. Then we configured a Realm and Identity Provider in RH-SSO for And connected RH-SSO as an OAuth provider to OpenShift via the Administrator console to allow access to our cluster through

This walkthrough only scratches the surface of what Red Hat SSO can do for your OpenShift Clusters. There are more granular ways of managing users and Identity Providers, which are not covered in this post. Please review and this blog post for additional information and recommended practices. For additional information on using in Production please consult their documentation here:

We hope this guide will provide you with a good overview of setting up as a trusted Identity Provider for your OpenShift 4 clusters.


How-tos, Security, OpenShift 4

< Back to the blog