Configure Keycloak

This page describes how to configure a Keycloak instance as an external IdP for the fulfillmenttools platform. 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 (upper 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.

Browse to Clients (on the left navigation pane) and select Create client to open the client configuration wizard.

In the first step of create client wizard, select an OpenID Connect type and an Client ID (e.g., fulfillmenttools-production-environment). Press Next afterward.

In the second step of the wizard activate the Implicit Flow. Press Next afterward.

In the wizard's third step, add 3 Redirect URIs. These 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

Press Save to create the client.

OAuth Client was created successfully . The Client ID must later be supplied to the fulfillmenttools platform 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 (e.g., 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.

In the following screenshot, the administrator role is created. This has to be done for SUPERVISOR and FULFILLER similarly.

Adding (facility) groups to the token

fulfillmenttools models the assigned facilities to a user using Keycloak groups. In the Keycloak administration console, select the Client 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.

Now, all groups of a user are put into the token. The fulfillmenttools platform leverages this to identify which user is allowed to access a facility on the fulfillmenttools platform.

Disable "Full scope allowed"

In the Keycloak administration console, select the Client 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:

If the OpenID scope is unavailable on the Keycloak instance, create it in the admin console (Client Scopes in the left navigation pane).

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 the fulfillmenttools platform, execute the following call:

POST https://tenant-name.api.fulfillmenttools.com/api/configurations/oidcproviders

{
    "name": "Keycloak Login",
    "status": "ACTIVE",
    "clientId": "{CLIENT_ID}",
    "clientSecret": "{CLIENT_SECRET}",
    "issuer": "https://{URL}/realms/{realm}",
    "customParameters": [],
    "assignedGroups": [
        {
            "group": "{KEYCLOAK_GROUP_NAME}",
            "facilityRefs": [
                "{FACILITY_ID_1}",
                "{FACILITY_ID_2}"
            ]
        }
    ]
}