Add documentation for how to configure CHT instance for SSO

[jkuester]

Should include a full tutorial setup + user provisioning.

Also would be helpful to note how it can be used with the Bulk User Upload functionality.

[jkuester]

Local Keycloak Instance (for testing with local development environment)

• Run your local development CHT instance via npm run dev-api
  • TODO Currently requires the code in the benkags:9765-support-oidc-flow branch.
  • These steps are not intended to work when running the CHT from within Docker (e.g. in via docker-helper).
• Start the Keycloak Docker container:

  docker run --name keycloak -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=medic -e KC_BOOTSTRAP_ADMIN_PASSWORD=password quay.io/keycloak/keycloak start-dev

• Open Keycloak at http://localhost:8080 in browser.
  • Login with medic/password
• Add new user in Keycloak:
  • Navigate to "Users" > "Add user"
  • Enter data for new user. E.g.:
    • Username - test
    • Email - test@test.com
  • Create the user and then navigate to the user's "Credentials" tab and select "Set password"
    • Set a password for the user (optionally uncheck "Temporary" so you do not have to set a new password on first login)
• Add new Client in Keycloak:
  • Navigate to "Clients" > "Create Client"
    • Client Type: OpenID Connect
    • Client ID: cht-test
    • Client authentication: On
    • Authentication Flow: Standard flow
    • Valid redirect URIs: http://localhost:5988/medic/login/oidc/get_token
      • TODO This path might change based on review comments...
  • Once the client is created, navigate to "Credentials" and copy the "Client Secret" value.
• Configure CHT to use Keycloak as OIDC provider:
  • In your app config directory update your base_settings.json or app_settings.json file to contain:

        "oidc_provider": {
          "client_id": "cht-test",
          "discovery_url": "http://localhost:8080/realms/master/.well-known/openid-configuration",
          "allow_insecure_requests": true
        },

    • (Note that allow_insecure_requests is required when connecting to the OIDC server via HTTP instead of HTTPS. This setting should not be used in production.)
  • Upload the config to the CHT with cht --local compile-app-settings upload-app-settings
• Set Client Secret in CHT instance:
  • Use the /api/v1/credentials REST api to set the client secret as the oidc:client-secret credential.

  curl -X PUT http://medic:password@localhost:5988/api/v1/credentials/oidc:client-secret \
       -H "Content-Type: text/plain" \
       --data "{{client_secret_from_keycloak}}"

• Create CHT user:
  • TODO Currently UI for adding SSO user is only in benkags:9761-sso-user-management-frontend
    • The workaround is to just add a normal user with the proper email value and then update the _users doc for that user to include "oidc": true via Fauxton
  • Navigate to the CHT instance in your browser: http://localhost:5988/ and login as the admin user
  • From the "App Management" console, go to "Users" > "Add user"
    • User name: test (can be any unique value)
    • Email-address: test@test.com (this must match the email for the Keycloak user)
    • Enable login Via SSO: Checked
• Logout as the Admin user.
• From the CHT login screen, select "Login with SSO"
  • Your browser will be redirected to the Keycloak login screen
  • Enter the username/password for your Keycloak user
  • You will be redirected back to the CHT app and logged in as your CHT user
    • TODO Currently CHT login not working in branch code due to user mapping.

References

• Keycloak Docker Quickstart
• Also see Select an Identity Provider service for development cht-core#9737 for more on configuring Keycloak with SSL and Docker Compose.

[jkuester]

Microsoft Entra (Azure AD)

• Login to the Microsoft Entra console at https://entra.microsoft.com
  • You will need a Microsoft Azure account. (I was able to create one for free, but it did require me to enter my credit card info.)
• Add new user in Entra:
  • Navigate to "Users" > "All users" > "New user" > "Create new user"
  • Enter details for your test user. Specifically note the "Mail nickname" value as this will need to match the email value for your CHT user.
  • Be sure to copy the generated password or replace it with one that you know.
• Add new Client in Entra:
  • Navigate to "Applications" > "App registrations" > "New registration"
  • Add a display name to identify the client. E.g. CHT Test Instance
  • Under "Redirect URI (optional)" select web
    • Enter http://localhost:5988/medic/login/oidc/get_token as the redirect URI
    • TODO This path might change based on review comments...
  • After registering the client, navigate to "Certificates & secrets" > "Client secrets" > "New client secret"
    • Add a new secret and copy the Value string
  • On the client app's "Overview" page, note the value displayed for "Application (client) ID". This is the client_id value.
  • From the "Overview" page, open the "Endpoints" modal and make a note of the "OpenID Connect metadata document" link value. This is the discovery_url.
• Configure CHT to use Entra as OIDC provider:
  • In your app config directory update your base_settings.json or app_settings.json file to contain:

        "oidc_provider": {
          "client_id": "{{your_client_id}}",
          "discovery_url": "{{your_discovery_url}}"
        },

  • Upload the config to the CHT with cht --local compile-app-settings upload-app-settings
• Set Client Secret in CHT instance:
  • Use the /api/v1/credentials REST api to set the client secret as the oidc:client-secret credential.

  curl -X PUT http://medic:password@localhost:5988/api/v1/credentials/oidc:client-secret \
       -H "Content-Type: text/plain" \
       --data "{{your_client_secret}}"

• Create CHT user:
  • TODO Currently UI for adding SSO user is only in benkags:9761-sso-user-management-frontend
    • The workaround is to just add a normal user with the proper email value and then update the _users doc for that user to include "oidc": true via Fauxton
  • Navigate to the CHT instance in your browser: http://localhost:5988/ and login as the admin user
  • From the "App Management" console, go to "Users" > "Add user"
    • User name: test (can be any unique value)
    • Email-address: test@test.com (this must match the email for the Entra user)
    • Enable login Via SSO: Checked
• Logout as the Admin user.
• From the CHT login screen, select "Login with SSO"
  • Your browser will be redirected to the Microsoft login screen
  • Enter the credentials for the test user you created in Entra and accept the prompts that follow.
  • You will be redirected back to the CHT app and logged in as your CHT user
    • TODO Currently CHT login not working in branch code due to user mapping.

[mrjones-plip]

Above two comments moved to Docs PR

[jkuester]

Just wanted to capture here that there may be some challenges connecting a CHT instance running locally in Docker (e.g. via docker-helper) to a Keycloak instance also running locally in Docker. This is because of the back-channel request that the CHT server needs to make to the OIDC provider. Somehow we will need to figure out how to address the Keycloak instance with a URL that can be resolved both by the user's browser and by the CHT instance running in the Docker container...

[benkags]

Some more reference on OIDC setup using Entra ID medic/cht-core#9738 (comment)