The Keycloak service running at sso.massopen.cloud
is a production facing Keycloak for authentication and authorization
of MOC public facing services.
There is one Keycloak Realm moc defined for all MOC services.
Users of MOC services include the MOC Ops team, Red Hat Open Accelerator team, and customers of MOC cloud services.
Users are authenticated through CILogon as the primary identity provider of the moc Realm.
The MOC Keycloak service is deployed on an Elastic Kubernetes Service deployed on Amazon Web Services. This Kubernetes cluster was installed to provide public access to highly available Keycloak and Coldfront services for the MOC. The configuration for the moc-services EKS cluster was made in this pull request.
Before deploying Keycloak to the moc-services Kubernetes cluster, a PostgreSQL database is required. The Crunchy Postgres Operator was installed with Kustomize GitOps to the moc-services Kubernetes cluster. A PostgresCluster resource was created with Kustomize GitOps to store the Keycloak and Coldfront databases.
With a database in place for Keycloak, the Keycloak Operator was installed with Kustomize GitOps to the moc-services Kubernetes cluster. A Keycloak resource was created with Kustomize GitOps to integrate Keycloak with the database, and make Keycloak publicly available at sso.massopen.cloud.
New users that access MOC services will be required to logon through CILogon, validate their email address, and accept a EULA before being granted access. The MOC has SMTP credentials configured in AWS Secrets Manager. To provide Keycloak with these credentials, OpenTofu SMTP credentials configuration were configured.
MOC services are all provided by one Keycloak Realm called moc.
Here is the OpenTofu configuration of the moc Realm,
which loads the SMTP credentials from AWS Secrets Manager,
and configures the MOC specific moc_localization terms.html.
All users authenticate by default to CILogon.
Here is the OpenTofu configuration of the CILogon Identity Provider in the moc realm that also references the cilogon_credentials from AWS Secrets Manager.
The MOC maintains several OpenShift clusters,
and authentication to each cluster console goes through Keycloak.
An OpenTofu object containing specific details of each OpenShift cluster is found in
OpenTofu configuration of OpenShift Clusters.
Each cluster specifies a cluster_name, openshift_redirect_uri, client_secret_name, and keycloak_client_uuid.
This is enough detail about each cluster to configure a Keycloak Client for each OpenShift cluster and push the Client Secret to AWS Secrets Manager for the OpenShift Cluster OpenTofu deployment to access.
An OpenTofu module named openshift_oidc is run for each OpenShift cluster. This configures the Keycloak Client with the expected OpenShift Cluster settings for OpenID Connect.
The MOC has a customized login workflow, based on CILogon that provides the right experience for a user to accept terms of the MOC, validate their email, and log in through CILogon and then into the OpenShift clusters or other MOC services they came to access.
- This is the customized browser auth flow that redirects users to the CILogon Identity Provider.
- This is the require existing user auth flow that expects the current Open Accelerator users to be preregistered, and auto links their email to their CILogon account on the first logon.
- This is the CILogon first broker auth flow that
review_profileDISABLED: disables reviewing their user profileconfirm_linkDISABLED: disables confirm link existing accountemail_verificationREQUIRED: requires the user to verify email addressverify_existing_account_by_reauthenticationDISABLED: disables verify existing account by re-authentication
MOC OpenShift Clusters have groups of users, like open-accelerator-admins, coldfront-admins, pi, and other projects that need to access resources on the OpenShift cluster.
These Groups are managed by Keycloak, and OpenShift knows the group of each user that logs in through Keycloak by the groups claim.
An OpenTofu list of these groups is found in
OpenTofu user group configuration.
-
Spin up a local keycloak instance:
make setupIt will take a few seconds for keycloak to become healthy.
-
Run
make init-local. This will:- override the S3 backend with a file backend
- rename
imports.tftoimports.tf.disabled - create
local-test.auto.tfvarsto point opentofu at the local keycloak instance
-
Run
tofu planortofu apply, etc.Email sent by the local Keycloak is captured by mailpit, viewable at http://localhost:8025.
make testruns the functional tests intests/against the local Keycloak, after amake bootstrap. They are written with pytest, and their dependencies are managed with uv. -
When you're done, run
make init-remote. This will undo the changes introduced bymake init-local. -
To tear down your local Keycloak instance:
make teardownThis will stop the containers, destroy the postgres backing store, and erase your local
terraform.tfstate*files.
Note that if you are applying this configuration against a fresh keycloak instance, you will need to run the following steps to bootstrap the environment:
tofu apply -var first_broker_login_flow='first broker login' -target keycloak_realm.moc
tofu apply -var first_broker_login_flow='first broker login'
tofu apply
The apply workflow (.github/workflows/apply.yaml) applies this
configuration on pushes to main. It authenticates to Keycloak using GitHub
Actions' OIDC identity (using federated client authentication).