Skip to content

Latest commit

 

History

History
280 lines (198 loc) · 6.47 KB

README.md

File metadata and controls

280 lines (198 loc) · 6.47 KB

JeMPI and Keycloak

This document is a guide of how JeMPI interfaces with keycloak for authentication. Will do this by covering

  1. What keyclock is in general (with particular focus on aspects more linked to JeMPI)
  2. How it integrates with JeMPI
  3. How to configure it within JeMPI
  4. How to configure JeMPI test keycloak server

Keycloak?

Keycloak is an open source application that allows for users to sign into applications using single sign authentication. It manages that whole process including keeping all the relevant authentication data, and handling logging out. To find out more please see https://www.keycloak.org/

Key aspects (relevant to JeMPI)

alt_text

Realm

A realm is the highest structure in keycloak, and can be likened to an organization. Within a realm you configure, clients, users etc

alt_text

Client

Clients are application/entities that can request keycloak to authenticate a user (see below), In theory multiple application can use the same client

Important Note:

For JeMPI to convert user session codes to user information, Client authentication must be enabled. This will result in the client getting a client secret you can use to query keycloak.

alt_text

Client -> Settings

alt_text

User

A user is someone that is registered on keycloak, and can authenticate via keycloak. Note: a user belongs to a realm but does not belong to a client. This means the same user can authenticate themselves using multiple clients (hence sso).

How it integrates with JeMPI

alt_text

Configuring keycloak within JeMPI

To configure JeMPI you need to configure 4 main variable found in _devops/linux/docker/conf/env/create-env-linux-high-1.sh_ / devops/linux/docker/conf/env/create-env-linux-low-1.sh . These are highlighted below detailing the purpose of each

Variable Description Default
KC_API_URL The url the API uses to access keycloak. When running in a docker swarm this could be the service host name (e.g http://keycloak-test-server:8080)
KC_REALM_NAME The realm you want to use (as defined above)
KC_JEMPI_CLIENT_ID The client you want to use (as defined above)
KC_JEMPI_CLIENT_SECRET The client secret (as defined above)
KC_JEMPI_ROOT_URL The url the request to authenticate will come from. In the case of JeMPI this is JeMPI UI’s url. \ \ Please note: this url is used to create the call back url, of which in JeMPI it is currently ${KC_JEMPI_ROOT_URL}/login

In addition to this you will need to set JeMPI UI specific variables, these case also be found in devops/linux/docker/conf/env/create-env-linux-high-1.sh / devops/linux/docker/conf/env/create-env-linux-low-1.sh .

Do note: If you are not running JeMPI UI within the docker swarm, you will need to update the appropriate variables in the .env file of the JeMPI project before starting it.

Variable Description Default
REACT_APP_JEMPI_BASE_API_HOST The domain on which JeMPI API is running.
REACT_APP_JEMPI_BASE_API_PORT The port on which JeMPI API is running. 50000
REACT_APP_MOCK_BACKEND Should be set to ‘false’ in most cases. Only enable for crude testing of JeMPI UI. Should be set to ‘false’ for Keycloak authentication false
REACT_APP_ENABLE_SSO Should be set to ‘true’ for keycloak authentication false
KC_FRONTEND_URL The url the ui will access keycloak from. In the case of keycloak running in docker with the port exposed it will be http://localhost:8080

Once these variables are set up, you should be able to start JeMPI as normal and authentication should happen via keycloak. The workflow of this is represent pictorially below

alt_text

  1. Login screen when not authenticated

alt_text

  1. Logging in via keycloak

alt_text

  1. JeMPI once logged in

Configuring JeMPI test keycloak server

The above instructions assume you have a keycloak server already configured elsewhere. If not, JeMPI bundles a test version of keycloak which it uses. Please note, the version is a development version, and should not be used in production.

To use it:-

  1. Update the JeMPI variable above to use the test server one. These are highlighted below. Note: By default these variables are already set correctly.
REACT_APP_ENABLE_SSO true
KC_REALM_NAME jempi-dev
KC_JEMPI_CLIENT_ID jempi-oauth
KC_JEMPI_CLIENT_SECRET Nsuhj2lQiCgSE7eVPLBgnLEEeaijufeh
KC_API_URL http://keycloak-test-server:8080
KC_FRONTEND_URL http://localhost:8080
KC_TEST_DB key_clock_test_db

  1. Start JeMPI normally. The key username details are below:

    Username: dev-user

    Password: dev_password_only

    The admin use for the keycloak server is

    Username: admin

    Password: admin

Notes:

  • The keycloak server takes a minute to two to startup, and be ready
  • Once it starts up it import the jempi-dev realm (with setting matching the above)
  • In the case that this fails, you can alway run the script devops/linux/docker/helper/keycloak/realms/import.sh directly
  • Also note, there is an export script as well (in case you want to keep a particular configuration). See devops/linux/docker/helper/keycloak/realms/export.sh