Configure Keycloak

This page describes what you have to configure in your keycloak instance. Log in with an admin user to the administrator console in keycloak; the default URL is: https://<your-keycloak-instance>/admin/master/console/.

Create a Client

If you have access to 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 you use (typically a test and a production environment), you need to 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, we need to add 2 Redirect URIs. These have the pattern:

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

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

Press Save to create the client.

You have successfully created an OAuth Client. 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, you now have a tab Credentials. Select Client Id and Secret. The Client Secret must be supplied to fulfillmenttools at a later step via API.

Create Client Roles

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

You have to add 3 roles: ADMINISTRATOR, SUPERVISOR and FULFILLER. You can choose an arbitrary Description. The Role name must be one of the above-mentioned roles: ADMINISTRATOR, SUPERVISOR or FULFILLER.

After you created the 3 roles, your app roles should look similar to this:

Linking Client Roles to users/groups

Next, we need to link keycloak groups to these client roles. You can add individual keycloak users to these groups to assign roles to users.

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

Typically, you have 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, we need to 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. You typically create 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, we have configured the administrator role. This has to be done for SUPERVISOR and FULFILLER similarly.

Adding (facility) groups to the token

We model 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. We use 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. We need the email, profile, and openid scopes:

If the openid scope is unavailable on your keycloak instance, you can create it in the admin console (Client Scopes in the left navigation pane).

Summary

You need to gather the following information to configure the external IDP via API:

• CLIENT_ID

  • This is the Client ID of your Client in keycloak

• CLIENT_SECRET

  • This is the value of the secret you 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, you need to execute the following call:

POST https://your.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}"
            ]
        }
    ]
}