Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

The migration to Keycloak is necessitated by the planned deprecation of Oauth2 Authorization Server by Spring Security in 2021 in favour of Keycloak.

Below are the key advantages of using Keycloak for identity management:

  • No overhead work to maintain and improve user management as in the case of a custom solution

  • Ability to utilize and leverage on other open source tools using existing standards

  • Ability to have single sign-on for all systems for one user

  • There is an audit trail for security and compliance measures

Architecture

System Architecture for Web-based Applications Using Authentication Code for Implicit Grant Types

This method requires that credentials collection is done by the identity management system. The user is redirected to a login page availed by the identity management. The authenticating application does not collect a user's credentials.

See the flow below:

  1. Users are pre-configured in Keycloak by a Keycloak administrator.

  2. A user requesting access to OpenSRP Web is redirected to the Keycloak login form.

  3. They are prompted to enter an existing username and password.

  4. The credentials are validated against entries in the Keycloak database.

  5. On successful login, a bearer access token is generated.

  6. The user is redirected back to OpenSRP, with a bearer access token attached.

  7. OpenSRP Web then attaches the bearer access token for requests to OpenSRP Server API.

  8. On receipt of API requests, OpenSRP Server API validates the access token against the Keycloak Identity System before performing actions initiated by the calls.

System Architecture for Android Applications Using Password Grant Type

This grant type requires that a user’s credentials be collected by the application. The application then forwards the credentials to the identity management system which verifies the credentials and returns an access token.

  1. Users are pre-configured in Keycloak by a Keycloak administrator.

  2. A user requiring access to OpenSRP API sends is a username and password to Keycloak.

  3. The credentials are validated against entries in the Keycloak database.

  4. If valid, a bearer access token is generated and return to the calling application.

  5. The client then avails this bearer token for requests to the OpenSRP Server API.

  6. On receipt of API requests, OpenSRP Server API validates the access token against the Keycloak Identity System before performing actions initiated by the calls.

System Architecture for Android Applications Using Password Grant Type

Custom Login/Decoupling from Keycloak API

With the above architecture, if we desire to use a custom login page we would have to customize Spring Security configuration so that OpenSRP login page defined in the application is used. On data submission, a JSON payload is created as per Keycloak specifications and a Keycloak API request is invoked which will return the access and refresh tokens.

Decoupling from Keycloak User and Role Management

It is possible to create a web UI for defining users, roles and user roles mapping. These are then saved in Keycloak via a Rest API.

A Keycloak superadmin would have to be configured in playbooks to enable such access via API.

Alternatively during deployment a Keycloak client can be configured that uses client credentials that can be used for making API calls for setting up Keycloak.

Implementation Details

The generic implementation is expected to cater for any Identity Management solution.

The considerations for this are:

  • The tool needs to be easily replaceable

  • It should not warrant massive changes in other applications that use it

  • The integration should be minimal and based on protocols only

  • Decoupling Implementation where we are only integrating with the protocol and not the tool

    • So that we can change the tool without changing the other systems

    • Have a minimal part integrating with Keycloak

System Interaction

What the architecture would look like for deployment? Storage, how services are exposed,

  • How OpenSRP connects with Keycloak?

    1. There is a native interface. Redirect to Keycloak

    2. Build our own user interface, making it easier to replace. Invoke Keycloak APIs to post/get the data

    3. Documentation to be looked at

Interaction Diagram for the Mobile Clients

Interaction Diagram for OpenSRP Web

Controls and Level of Access

OpenSRP or any other application using Keycloak defines the levels of access for the configured users. Access to resources by the user is controlled by the resource server.

Extensibility

Visit Keycloak Extensions page to view the available extensions.

Keycloak also has APIs that can be used by third party systems. For example, Jenkins supports authentication using Keycloak.

Supported Protocols

Keycloak supports the following protocols. Visit this page for more detail on supported protocols.

  • OIDC

  • SAML

Further Reading

  • No labels