Configure Keycloak

This page describes how to configure a Keycloak instance as an external IdP for fulfillmenttools. Log in with an admin user to the administrator console in Keycloak; the default URL is: https://<keycloak-instance>/admin/master/console/.

Create a Client

If there are existing multiple Keycloak realms, use the dropdown (top left corner) to select the correct realm, which should be used as external IDP for fulfillmenttools. For each fulfillmenttools environment (typically a test and a production environment), create a separate client in Keycloak. To do that, follow the steps below.

1

Create a client

Browse to Clients (in the left-hand navigation) and select Create client to open the client configuration wizard.

2

Select the client type

In the Client type dropdown, select OpenID Connect type, then input a Client ID (for example, fulfillmenttools-production-environment). Then click Next.

3

Activate implicit flow

Click the check box to activate Implicit flow and then click Next.

4

Add 3 Redirect URLs

They should have the pattern:

• https://ocff-<tenantName>-<pre|prd>.firebaseapp.com/__/auth/handler

• https://ocff-<tenantName>-<pre|prd>.web.app/__/auth/handler

• https://pick-<tenantName>-<pre|prd>.web.app/__/auth/handler

Then, click Save to create the client. Save the Client ID as it must be supplied to us via API.

Activate Authentication and Create Credentials (Client Secret)

On the Client configuration page activate Client authentication and press Save.

At the top of the Client, select the Credentials tab. Select Client Id and Secret. The Client Secret must be supplied to fulfillmenttools at a later step via API.

Create Client Roles

Now, create the client roles that correspond to the fulfillmenttools roles. Navigate to Roles and press Create role.

Create 3 roles: ADMINISTRATOR, SUPERVISOR and FULFILLER. Choose an arbitrary Description. The Role name must be one of the above-mentioned roles: ADMINISTRATOR, SUPERVISOR or FULFILLER.

The app roles should look similar to this:

Linking Client Roles to users/groups

Next, link Keycloak groups to these client roles. Individual Keycloak users can be added to these groups to assign roles to users.

In the Keycloak administration console, select Groups on the left navigation pane.

Typically, there exist three Keycloak groups, one for each fulfillmenttools role. By clicking Create group, create one Keycloak group for each fulfillmenttools role (for example, fft-role-administrator, fft-role-supervisor, fft-role-fulfiller).

Now, assign client roles to these groups. Therefore, select the created group in the Groups section.

Then, select Role mapping in the tabs and press Assign role. Create a total of three groups for a production setup, one for each role. Then, every member of the group is assigned the corresponding fulfillmenttools role.

Select the corresponding role from the client, and press Assign.

Adding (facility) groups to the token

fulfillmenttools models the assigned facilities to a user using Keycloak groups. In the Keycloak administration console, select Clients and the Client scopes tab. Select the <client ID>-dedicated entry:

Then, select Configure a new mapper.

Select Group Membership.

The name of the token mapper must be groups. Then press Save.

Disable "Full scope allowed"

In the Keycloak administration console, select Clients and the Client scopes tab. Select the <client ID>-dedicated entry:

Then, open the Scope tab and disable the Full scope allowed:

Configure Client Scopes

In the client configuration, select the Client Scopes tab. Add the email, profile, and openid scopes:

Summary

Gather the following information to configure the external IDP via API:

• CLIENT_ID

  • This is the Client ID of the Client in Keycloak

• CLIENT_SECRET

  • This is the value of the secret created

• Keycloak Facility Group Names

  • group names of the Keycloak groups representing a facility

• FACILITY_ID_1, FACILITY_ID_1

  • id of the facilities in fulfillmenttools that this group should have access to

To register the OIDC provider to fulfillmenttools, execute the following call: