Keycloak

Using CHT with Keycloak

Introduced in 4.20.0. This feature is only compatible with cht-android version v1.5.2 or greater.

Introduction

These steps document how to configure Keycloak as the Single Sign On (SSO) identity provider for the CHT. As well, it walks through provisioning a single user for SSO.

Prerequisites

Keycloak server - ensure you are running a supported version
CHT server - ensure you are running version 4.20.0 or later
DNS Entries for CHT and Keycloak
TLS enabled on CHT and Keycloak

Start with creating a Keycloak compose file and two cert files in a new ~/cht-keycloak directory by running this code:

mkdir -p $HOME/cht-keycloak/data
curl -so $HOME/cht-keycloak/server.crt https://local-ip.medicmobile.org/fullchain
curl -so $HOME/cht-keycloak/server.key https://local-ip.medicmobile.org/key
cat > $HOME/cht-keycloak/compose.yaml << EOF
services:
  keycloak:
    image: quay.io/keycloak/keycloak
    environment:
      KEYCLOAK_ADMIN: medic
      KEYCLOAK_ADMIN_PASSWORD: password
      KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/server.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/server.key
    ports:
      - "8443:8443"
    command: start-dev
    volumes:
      - $HOME/cht-keycloak/server.crt:/opt/keycloak/conf/server.crt
      - $HOME/cht-keycloak/server.key:/opt/keycloak/conf/server.key
      - $HOME/cht-keycloak/data:/opt/keycloak/data
EOF
cd $HOME/cht-keycloak
docker compose up -d

The Keycloak instance is accessible on your Docker Helper URL, but on port 8443. For example https://192-168-68-26.local-ip.medicmobile.org:8443. The username is medic and the password is password.

Now create an instance of Docker Helper.

Keycloak Setup

Open Keycloak

Be sure you’re logged in

Add new Client

Add new Client in Keycloak by going to “Clients” > “Create Client”. Be sure to replace CHT_URL with the production URL of your CHT instance. If you’re on a development instance be sure to include the port:

Client Type: OpenID Connect
Client ID: CHT
Client authentication: On
Authentication Flow: Standard flow
Valid redirect URIs: https://<CHT_URL>/medic/login/oidc

Create new Client

Client ID

Client authentication

Valid redirect URIs

Copy Secret

On the new CHT client go to “Credentials” and copy the “Client Secret” value. You’ll need this later when configuring the CHT.

copy.secret.png

CHT Setup

CHT App Settings

In the config directory for your app, update your app_settings.json file to contain this additional JSON at the end, before the very last }

Be sure to replace KEYCLOAK_URL with the production URL of your Keycloak instance and CHT_URL with the production URL of your CHT instance. If you’re using a development instance, be sure the CHT_URL includes your port.

    "oidc_provider": {
      "client_id": "CHT",
      "discovery_url": "https://<KEYCLOAK_URL>/realms/master/.well-known/openid-configuration"
    },
    "app_url": "https://<CHT_URL>/"

Upload CHT config

Upload the config using CHT Conf. Replace CHT_URL with the production URL of your CHT instance, USER with your admin user and PASSWORD with your password:

cht --url=https://<USER>:<PASSWORD>@<CHT_URL> compile-app-settings upload-app-settings

Upload the config using CHT Conf. Replace CHT_URL with the docker helper URL, including port:

cht --url=https://medic:password@<CHT_URL> compile-app-settings upload-app-settings

Client Secret in CHT

Use the /api/v1/credentials REST api to set the client secret as the oidc:client-secret credential.

Be sure to replace SECRET with the value from step 5 above. As well, replace CHT_URL with the production URL of your CHT instance, USER with your admin user and PASSWORD with your password:

curl -X PUT https://<USER>:<PASSWORD>@<CHT_URL>/api/v1/credentials/oidc:client-secret \
     -H "Content-Type: text/plain" \
     --data "<SECRET>"

Be sure to replace SECRET with the value from step 5 above. As well, replace CHT_URL with the docker helper URL, including port:

curl -X PUT https://medic:password@<CHT_URL>/api/v1/credentials/oidc:client-secret \
     -H "Content-Type: text/plain" \
     --data "<SECRET>"

Upon success, curl should show the JSON {"ok":true} .

Further, going to the CHT login screen should now show an extra login button “Login with SSO”. You may need to hold down the “shift” key and click reload to clear the browser cache: