Red Hat SummitRed Hat blog
In this article, we will walk through how to integrate Red Hat Single Sign-on (RH-SSO) with Login.gov as an identity provider for authenticating against OpenShift clusters. This configuration will allow you to control user access to your OpenShift clusters through Login.gov, 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 Login.gov 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 Login.gov 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 Login.gov account and application.
Set up Login.gov account
In order to set up the appropriate access for Login.gov, we went through the Login.gov documentation and found that Login.gov 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 https://secure.login.gov/ log in or create a new account.
After creating a Login.gov account, navigate to https://idp.int.identitysandbox.gov/ and log in. This will redirect you to: https://dashboard.int.identitysandbox.gov/ where we will begin setting up the Login.gov project application. Note, you will need to set up your own team or be provided one, which should look like this…
Create Login.gov Test App
The Test app in Login.gov allows an external provider (in our case, OpenShift) to communicate with Login.gov in order to authenticate a user.
Once we have logged in to, we can create a new test application with: https://dashboard.int.identitysandbox.gov/service_providers/new
Click “Create a new test app” and that will lead us to…
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: https://console-openshift-console.apps.cluster-name.example.com/dashboards **
Redirect URIs: https://keycloak-security-operations.apps.cluster-name.example.com/auth… **
Attribute Bundle: Check “email”, “first_name”, “last_name”
Active: Yes
Click Create/Update
* Note: please replace `agency_name` and `app_name`
** Note: please replace `cluster-name.example.com` 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 Login.gov 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.
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 CNCF.io's blog.
If you click on `Red Hat Single Sign-On Operator` above it will take you to the following screen.
Here we will click “Create Instance”
Keep all the defaults, scroll to the bottom and click “Create”
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 Login.gov, 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.
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 Login.gov, especially if you wish to use multiple Identity Providers with this SSO.
Now, let’s add Login.gov 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: Login.gov
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: https://idp.int.identitysandbox.gov/.well-known/openid-configuration
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:
- Client Authentication: JWT signed with private key
- Client ID: urn:gov:gsa:openidconnect.profiles:sp:sso:agency_name:app_name *
- Authorization URL: https://idp.int.identitysandbox.gov/openid_connect/authorize?acr_values=http%3A%2F%2Fidmanagement.gov%2Fns%2Fassurance%2Floa%2F1 **
- Validate Signatures: Off ***
*Note this came from what we specified in Login.gov dashboard.
**We discovered there were the “ACR value errors” returning from Login.gov. While ACR values are not required by OIDC, Login.gov will not function without passing them through. We solved this by looking at: https://identity-dev-docs.18f.gov/oidc/#authorization and then taking http://idmanagement.gov/ns/assurance/loa/1 and encode it to:
http%3A%2F%2Fidmanagement.gov%2Fns%2Fassurance%2Floa%2F1 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 Login.gov (https://idp.int.identitysandbox.gov/api/openid_connect/certs), even though these keys are optional via https://tools.ietf.org/html/rfc7517. 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 https://www.keycloak.org/docs/latest/server_admin/.
It should now look like this...
Click “Save”.
At this point, the configuration has allowed our Red Hat Single Sign-on to talk with Login.gov. 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, Login.gov, with our OpenShift OAuth system.
Keycloak.org 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, Login.gov, 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*: https://oauth-openshift.apps.cluster-name.example.com/*
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 Login.gov. 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…
Click on “router-ca”.
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 Login.gov 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”.
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: https://keycloak-security-operations.apps.cluster-name.example.com/auth/realms/master **
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 `cluster-name.example.com` 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 Login.gov
The last piece of necessary configuration is to add the Certificate that RH-SSO generates into Login.gov 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 Login.gov.
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 Login.gov test app page and paste it into “Public Certificate”.
Click “Update”.
Verify and Conclusion
With the necessary configuration complete to integrate Login.gov, 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 Login.gov sign in on the right!
Click Login.gov and it will redirect you to a page similar to the following:
Login.gov will now pass authentication back to your cluster and create your user if it does not exist.
Click Submit and you will be redirected to the OpenShift console.
Let’s recap. First, we configured Login.gov 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 Login.gov. And connected RH-SSO as an OAuth provider to OpenShift via the Administrator console to allow access to our cluster through Login.gov.
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 https://docs.openshift.com/container-platform/4.7/authentication/using-rbac.html and this blog post https://www.redhat.com/en/blog/openshift-single-sign-sso for additional information and recommended practices. For additional information on using Login.gov in Production please consult their documentation here: https://developers.login.gov/production/#production-configuration.
We hope this guide will provide you with a good overview of setting up Login.gov as a trusted Identity Provider for your OpenShift 4 clusters.
