[SSO] KeyCloak Setup and Implementation

[snyaggarwal]

Tasks (High Level)

• Setup Keycloak docker container
• Configure Keycloak (manual) -- realm,client,roles
• Use django-keycloak-auth or some generic django+openid-connector package.
• Integrate OCL API with KeyCloak using above package (or custom) and using openid-connect (not SAML)
• Plugin authenticate process to get user token
• Plugin Signup Process.

Questions:

• Whats the password encryption scheme of KeyCloak? Can the password be migrated from django to KeyCloak?

Other Notes:

• TermBrowser may need to talk to KeyCloak for initiating signup process via keyCloak
• Django should always ask keycloak if user’s authenticated or not

[paynejd]

Migration to KeyCloak will change the API tokens for all users

[snyaggarwal]

Task Steps:

• KeyCloak Setup:

  • Docker container (part of ocl-api-core docker-compose.yml)
  • (manual) Create/Configure realm OCL-<env> (this should be different for each env)
  • Create Client (ocl-<env>) in OCL-<env> realm with base URL (ocl-qa with base URL https://api.qa.agrichain.com)
  • Set client's Access Type as confidential and copy client-id/secret from Credentials
  • Add roles in client if any.
  • Create Users in OCL-<env> realm, set credentials

• Configuring OCLAPI:

  • Update the following env vars:
    • OIDC_SERVER_URL
    • OIDC_SERVER_INTERNAL_URL (should be same as OIDC_SERVER_URL for non-dev)
    • OIDC_REALM
    • OIDC_RP_CLIENT_ID
    • OIDC_RP_CLIENT_SECRET

[snyaggarwal]

TODO:

• Signup
• Forgot password
• Token expiry handling on TermBrowser

[rkorytkowski]

@snyaggarwal I think we need to revisit the approach a bit and when switching to use oidc server we should really be redirecting users to Keycloak for login / logout / singup / forgot password. We can then easily rely on Keyclock providing MFA, adding other identity providers like Google, Facebook, etc. We are also more secure as OCLAPI code is not storing or handling any user credentials and we are not responsible for any password leaks. See https://oauth.net/2/grant-types/password/ which explicitly says it is not recommended that this grant be used at all anymore.

[rkorytkowski]

https://www.keycloak.org/docs/latest/server_development/#_themes is how we would go about customizing the keycloak theme.

[snyaggarwal]

@rkorytkowski Alight! I am working on the setup.

[snyaggarwal]

https://docs.google.com/document/d/116PlRJv1-5qAIADkkaVnkxnjkwKBPWqQ95-wJ2KZLFw/edit

[paynejd]

Key behaviors that need to be tested as deploy on the QA and staging environments:

• Sign up
• Sign in
• Sign out
• Forgot/Reset password
• Admin has a few more actions

[paynejd]

Next stesps:

• Merge into master, deploy to QA
• Test in QA
• Sunny to write document describing how a client should interact with KeyCloak, using Dictionary Manager as the example

[snyaggarwal]

@rkorytkowski Moving this to Code Review.

[snyaggarwal]

@paynejd @rkorytkowski A new Client integration documentation

[snyaggarwal]

@jamlung-ri @paynejd @rkorytkowski This is now merged with master and deployed on QA (with SSO disabled)

[jamlung-ri]

@paynejd and @jamlung-ri to test this on Dev

[rkorytkowski]

We'll enable it in OCL online with #1405, which awaits #1389.

[paynejd]

Note that OID-compatible features for the API were merged into master and were deployed to all environments. KeyCloak is deployed for OCL Online and only a single instance will be used for all environments.

Currently, SSO has been enabled only on dev, and that included a migration of user accounts from dev.

Next steps include:

• Integrating OpenMRS Dictionary Manager with KeyCloak and testing
• Migrating user accounts and activating SSO in each environment + testing
• Identifying dependencies between the OCL Online rollout and upcoming support for the WHO-hosted Azure Active Directory deployment