Single Sign-On

Setting up Single Sign On with the CHT

Overview

The CHT supports Single Sign-On (SSO) via integration with an external authentication server. Users connecting to a CHT instance authenticate with their SSO credentials instead of needing a CHT-specific username and password.

SSO authentication is implemented with the industry standard OpenID Connect (OIDC) protocol. Any OIDC-compliant authentication server can be integrated with the CHT. For example:

• Keycloak - Free and open-source, self-hostable identity and access management server
• Microsoft Entra ID - Paid, cloud-based identity and access management service.

Quick Start

1. Add a new client to your OIDC Provider with the redirect URL of https://<CHT_URL>/medic/login/oidc. You will need your client id, client secret, and the discovery URL of your OIDC Provider for the next steps. Be sure to replace CHT_URL with your real URL.

2. Add the Client App ID (APP_ID), OIDC Provider discovery URL (WELL_KNOWN_OIDC_URL) and CHT URL (CHT_URL) to your app_settings.json using CHT Conf. Be sure to replace APP_ID, WELL_KNOWN_OIDC_URL and CHT_URL with your real URLs:

   "oidc_provider": {
     "client_id": "<APP_ID>",
     "discovery_url": "https://<WELL_KNOWN_OIDC_URL>"
   },
   "app_url": "https://<CHT_URL>/"

3. Upload the secret from step 1 to the CHT. Be sure to replace CHT_URL , USER, PASSWORD and SECRET with the correct values: curl -X PUT https://<USER>:<PASSWORD>@<CHT_URL>/api/v1/credentials/oidc:client-secret -H "Content-Type: text/plain" --data "<SECRET>"

4. Before logging into the CHT, each SSO user must have a CHT user provisioned with an “SSO Email Address” that matches the email address configured for the user with the OIDC Provider.

5. Use the “Login with SSO” button on the CHT login page.

Detailed guides

For more detailed guides and requirements, see the following documents: