Deploy and configure Keycloak for NBS 7

Keycloak is the authentication service that lets users sign in to the NBS 7 web UI. It provides authentication for modernization-api, nbs-gateway, dataingestion-service, and nnd-service, and, like the services in Deploy core Kubernetes services, it is a core service. This page covers how to install Keycloak, configure the authentication setup that the NBS 7 microservices require, and validate Traefik and Keycloak together. Complete these steps before you deploy the NBS 7 microservices.

Already running Keycloak? If your jurisdiction operates its own Keycloak and you want NBS 7 to authenticate against an existing realm, follow Integrate NBS 7 with an existing Keycloak instead of this page. This page installs the NBS-provided Keycloak and imports the NBS realms.

On this page

  1. Prerequisites
  2. Create the Keycloak database
  3. Configure the Helm chart
  4. Deploy Keycloak
  5. Access the Keycloak admin interface
  6. Create the NBS and nbs-users realms
  7. Import base users and clients
  8. Set the login theme (optional)
  9. NBS 6 user requirement
  10. Final validation of Traefik and Keycloak
  11. Import service clients and retrieve secrets
  12. Next steps

Prerequisites

Before you begin the procedures on this page, locate the keycloak Helm chart in the NEDSS-Helm repository for NBS version 7.13.

Create the Keycloak database

Create the Keycloak database and database user before you deploy the Helm chart.

Any compatible SQL client works for this step, including SQL Server Management Studio (SSMS).

  1. Using your SQL client, authenticate into your database server:

    Field Value
    DB Endpoint Your database endpoint
    Username admin
    Password Your database admin password

  2. Run the following script to create the Keycloak database and database user. Replace 'EXAMPLE_KCDB_PASS8675309' with a complex password that meets your organization’s standards. Store this password securely. You will need it in values.yaml in Configure the Helm chart.

    use master
  IF NOT EXISTS(SELECT * FROM sys.databases WHERE name = 'keycloak')
  BEGIN
    CREATE DATABASE keycloak
 END
GO
  USE keycloak
GO

BEGIN
CREATE LOGIN NBS_keycloak WITH PASSWORD = 'EXAMPLE_KCDB_PASS8675309';
CREATE USER NBS_keycloak FOR LOGIN NBS_keycloak;
EXEC sp_addrolemember N'db_owner', N'NBS_keycloak'
END

The following screenshot shows the keycloak database created under Databases in SQL Server Management Studio, confirming the script ran successfully.

SQL Server Management Studio Databases tree showing the keycloak database expanded under Databases, with its child nodes including Tables, Views, and Security

Configure the Helm chart

In values.yaml, update the following parameters:

Template value Parameter Description
<<EXAMPLE_KEYCLOAK_ADMIN_PASSWORD>> deployment.keycloak.env.keycloakAdminPassword Password for the Keycloak admin user. Use a complex password that meets your organization’s standards. The admin username, keycloakAdmin, defaults to admin.
<<EXAMPLE_KC_DB_USER_PASSWORD>> deployment.keycloak.env.kcDbPassword Password for the Keycloak database account. Must match the password you set in Create the Keycloak database.
jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=keycloak;encrypt=true;trustServerCertificate=true; deployment.keycloak.env.kcDbUrl Connection string for the Keycloak database. Replace EXAMPLE_DB_ENDPOINT with your database endpoint.
EXAMPLE_EFS_ID efsFileSystemId AWS only. The Amazon EFS file system ID from the AWS console or CLI. Provides persistent storage for Keycloak themes.
EXAMPLE_STORAGE_ACCOUNT_NAME azure.files.storageAccountName Azure only. The name of the Azure storage account that provides persistent storage for Keycloak themes.
EXAMPLE_RESOURCE_GROUP_NAME azure.files.resourceGroupName Azure only. The resource group that contains the Azure storage account.

Deploy Keycloak

Use the following steps to install the Keycloak Helm chart and verify the pod is running. The kubectl commands on this page require the cluster connection you configured in Connect to Kubernetes cluster.

  1. From the charts directory, install the Keycloak Helm chart. This step takes at least 5 minutes while the init container becomes available. See the README in charts/keycloak for details.

    helm install keycloak --namespace default -f keycloak/values.yaml keycloak

    After installation completes, the Keycloak database populates with its application tables, as shown in the following screenshot.

    SQL Server Management Studio Tables node expanded under the keycloak database, showing Keycloak application tables such as CLIENT, CLIENT_SCOPE, and CLIENT_SESSION

  2. Verify the pod is running before you continue:

    kubectl get pods -n default

Access the Keycloak admin interface

Use port forwarding to access the Keycloak web UI from your local machine.

Port forwarding is not supported by AWS CloudShell or Azure Cloud Shell by default. Run these commands from a system that has both network access to your Kubernetes cluster endpoint and a browser. If you completed the installation from AWS CloudShell or Azure Cloud Shell, switch to a jumpbox or desktop with network connectivity to your cluster endpoint.

  1. Set up port forwarding:

    kubectl port-forward deploy/keycloak-deployment 8080

  2. In a browser, navigate to http://127.0.0.1:8080/auth and select Administration Console.

    Keycloak welcome page at the /auth path with the Administration Console, Documentation, Keycloak Project, Mailing List, and Report an issue links

  3. Sign in using the adminUser and adminPassword values you configured in the Helm chart.

    Keycloak sign-in form with username and password fields and a Sign in button

After you sign in, the admin console opens to the master realm welcome page.

Keycloak admin console welcome page for the master realm, with the side navigation showing Clients, Client scopes, Realm roles, Users, Groups, Sessions, and Events

Create the NBS and nbs-users realms

Keycloak uses two realms for NBS 7: the NBS realm for service clients, and the nbs-users realm for user-facing authentication. Create both using the same procedure, with a different import file for each.

Realm Import file Purpose
NBS 01-NBS-realm-with-DI-client.json Contains service clients for data ingestion, NND, and SRTE data access. Seeds the di-keycloak-client service client in the same step.
nbs-users 02-nbs-users-realm.json Provides user-facing authentication for the NBS application and NBS gateway. Contains the client used by modernization-api and nbs-gateway for OpenID Connect (OIDC) login.

OIDC must be enabled when you deploy modernization-api and nbs-gateway. You configure OIDC during microservices deployment, not on this page. See Deploy NBS 7 microservices for OIDC configuration steps.

  1. From the side navigation, select Create realm. The following screenshot shows the realm selector open in the master realm, where the Create realm button appears:

    Keycloak side navigation with the realm selector open, showing the master realm and a Create realm button

  2. Upload the import file for the realm you’re creating, then select Create. The Realm name field auto-populates after upload. The following screenshot shows the NBS realm import with 01-NBS-realm-with-DI-client.json uploaded:

    Keycloak Create realm form with 01-NBS-realm-with-DI-client.json uploaded, JSON content visible in the resource file area, and realm name field populated with NBS

  3. Verify the realm and its clients are created successfully. After you create both realms, the realm selector lists all three realms. The following screenshot shows the selector after the nbs-users realm import:

    Keycloak realm selector dropdown listing the Keycloak master realm, NBS realm, and nbs-users realm

Import base users and clients

Import the base NBS users and development clients into the nbs-users realm:

  1. Select the nbs-users realm, then navigate to Realm settings > Action > Partial Import.

    Keycloak Realm settings page for the nbs-users realm, showing the General tab with realm configuration options

  2. Upload 03-nbs-users-base-users.json, select the three users, and select Import.

    The Partial import dialog shows the file uploaded with the three users selected for import.

    Keycloak Partial import dialog with 03-nbs-users-base-users.json uploaded and a 3 Users checkbox selected for import

    After the import completes, Keycloak confirms that all three users were added.

    Keycloak Partial import confirmation listing three added users: msa, nbs-users-admin, and superuser

  3. Upload 04-nbs-users-development-clients.json, select the one client, and select Import.

    The Partial import dialog shows the development client file uploaded and selected for import.

    Keycloak Partial import dialog with 04-nbs-users-development-clients.json uploaded and a 1 Clients checkbox selected for import

    After the import completes, Keycloak confirms that the client was added.

    Keycloak Partial import confirmation showing one added client named nbs-development

Set the login theme (optional)

You can use the pre-populated NBS login theme, keep the default Keycloak theme, or create a custom theme. The Keycloak Helm chart loads a sample NBS theme in a persistent volume mounted at /opt/keycloak/themes/nbs.

  1. Select the nbs-users realm.

  2. Navigate to Realm settings > Themes > Login and select your preferred theme.

    Keycloak Themes tab in Realm settings for the nbs-users realm, with the Login theme drop-down open showing base and keycloak options

NBS 6 user requirement

NBS 7 authenticates each user in Keycloak and then hands the username off to NBS 6. Every user who signs in to NBS 7 must exist as an active user_id in the NBS 6 Auth_user table. If the user is missing or not ACTIVE, Keycloak login succeeds but NBS 6 page access fails.

To confirm that a user’s NBS 6 account exists and is active, run the following query. The user_id must match the Keycloak username, and record_status_cd must be ACTIVE:

SELECT user_id, record_status_cd, nedss_entry_id
FROM NBS_ODSE.dbo.Auth_user
WHERE user_id = 'superuser';

Final validation of Traefik and Keycloak

This validation depends on the DNS records from Deploy core Kubernetes services and the Keycloak configuration on this page. Use a browser to verify the following:

  1. Navigate to https://app.<DOMAIN_NAME.TLD> and verify that the NBS 7 Welcome page is shown. The following screenshot shows the Welcome page from the NBS demo environment. Your Welcome page will differ.

    NBS 7 demo site Welcome page with a Login panel and a Login to NBS demo site button

  2. Select Login and verify that the Keycloak login page is shown.

    Keycloak login page for the NBS application with username and password fields and a Sign In button

  3. Open your browser’s developer tools. For example, in Chrome, select View > Developer > Developer Tools.

  4. Sign in and verify that authentication works and that the NBS 7 Home page is shown.

  5. In developer tools, select Network and select a .js file. Under Headers > Response headers, verify the following values:

    Cache-Control: max-age=1209600, immutable
Cross-Origin-Opener-Policy: same-origin
X-Frame-Options: Allow

    NBS 7 home page with browser console expanded to show the Network tab with verifiable values highlighted

Import service clients and retrieve secrets

The imported configuration seeds a random client secret for most service clients. You can regenerate these secrets or use them as generated. Retrieve and store each secret before you proceed to microservices deployment.

Client Realm Import needed Import file Used by
case-notification-service NBS ✓ Yes 08-nbs-users-case-notification-service.json Case notification service
di-keycloak-client NBS No Not needed Data ingestion service
nbs-modernization nbs-users No Not needed OIDC login for Modernization API and NBS Gateway
nnd-keycloak-client NBS ✓ Yes 05-nbs-users-nnd-client.json NND service
srte-data-keycloak-client NBS ✓ Yes 06-nbs-users-srte-data.json SRTE data access

Import the additional clients

For each service client that has Yes in the Import needed column of the clients table, complete the following steps:

  1. In the realm listed for that client, navigate to Realm settings, select the Action dropdown, and select Partial Import.
  2. Upload the import file listed for that client and select Import.

After each import completes, follow Retrieve a client secret to get the secret for that client.

Retrieve a client secret

Use the following steps to retrieve the secret for any service client in the clients table:

  1. In the realm listed for that client, navigate to Clients and select the client.
  2. Open the Credentials tab.
  3. Select the eye icon to reveal the secret and copy it.
  4. Store the secret securely in your organization’s secrets manager, such as AWS Secrets Manager or Azure Key Vault.

The following screenshots show this procedure for di-keycloak-client.

Keycloak Clients list in the NBS realm with di-keycloak-client highlighted in the Client ID column

The Credentials tab looks the same for the other clients, with the client-specific secret shown in the same field.

Keycloak Credentials tab for di-keycloak-client showing the masked client secret field with eye and copy icons and a Regenerate button

Next steps

Continue to Deploy NBS 7 microservices.