Keycloak Federated Login with Chris21

Overview

Mumba uses Keycloak, which is a third party authentication and user management system to handle our permissions and user authentications.

Mumba has designed a Chris21 Keycloak Plugin that creates a seamless migration experience for customers using Chris21 for their user authentication and would prefer to rather use Keycloak for authentication going forward.

This document outlines how the plugin operates along with various migration workflows.

Once the user has been successfully provisioned in Keycloak, all password and user management functions are controlled by Keycloak and can be configured within the Keycloak application.

Overview of the Keycloak Login Workflow

When a user logs in to the Mumba app for the first time, Keycloak will check to see if the user exists in the Keycloak database.

If the user exists in the Keycloak database they will be authenticated and directed to the Mumba dashboard.

If the user does not exist in the Keycloak database, the plugin will authenticate the user against Chris21.

If the user authenticates successfully against Chris21 then their first name, last name, ID and email will be imported into Keycloak. The Chris21 password is not copied across.

The user will then be prompted to create a new password. Once the user has created their password they will be passed to the Mumba dashboard.

What has in fact happened is that the user has created their password in Keycloak and has therefore completed the migration process from Chris21 to Keycloak.

Once the user account has been provisioned in Keycloak, any updates to the name and email address in Chris21 or in the Mumba application will be synchronised across all systems. However, passwords are never synchronised between Keycloak and Chris21.

Depending on your password expiration settings (e.g. 90 days), the password set in Keycloak will expire and the user will need to reset their password. This will have nothing to do with a user's Chris21 password as it is completely separate.

Login workflow for different types of users

Regular Users:

For regular login to the app, an employee can be setup in Chris21. They can then enter their Chris21 password on the Login page and Keycloak will validate them against Chris21 and then auto-import them into Keycloak. The user will immediately be asked to ‘change their password’ after login (really they are creating a new password in Keycloak).

Employees who have not had the app rolled out to them

Any employee with a valid Chris21 account and password will be able to login to the app, even if the app has not been deployed to them. If required, we can look to modify our integration to ensure the person has the app flag in Chris21 before we grant access.

Users who exist in C21 with an expired or forgotten password

For a user who exists in Chris21 with an expired or forgotten password who has not logged into the app (and therefore does not yet exist in Keycloak), when they use the ‘Forgotten Password’ we will validate only the user ID against Chris21 and ensure they are active before we auto-import them into Keycloak. Then, they will either need to create their password via the email sent to them or call the helpdesk to create their password.

Users who do not exist in C21

You can also manually setup people in Keycloak so you can have some users access the app that are not setup in Chris21.

Forgot Password

The Forgot Password feature can be used in two situations:

  1. Provisioning users in Keycloak who have forgotten their Chris21 password, or their Chris21 password has expired before they've been provisioning in Keycloak.

  2. If a user has forgotten their Keycloak password and they already have an existing Keycloak account.

Guide to using the "Forgot Password" feature

If you have forgotten your Keycloak or Chris21 password, or if your password has expired in Chris21, you will need to click on the "forgot password" link from the login page.

Step 2: Enter your ID into the forgot password field and click submit.

Keycloak will search to see if the user exists.

If the user does not exist, Keycloak will verify if the userid is valid in Chris21 and if so, it will create the user and import their firstname, lastname and email address.

If the username is not verified in Keycloak or in Chris21 then the record will not be saved in Keycloak.

Note: If Keycloak has been configured to allow multiple employees to use the same email address, the ability to use your email address to reset your password will be disabled for all users. In this case, you will only be able to use your User ID.

Step 3: An email with instructions on how to reset your password will be sent to the address linked with the account.

If the user does not have an email address, a helpdesk team member will be able to reset their password for them by following the standard "Helpdesk - Password Reset" workflow.

Please note, the helpdesk staff member will need to type in the user ID into the "forgot password" field in order for user to be provisioned in Keycloak. They can then search for the user and reset the password.