# 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:///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. {% stepper %} {% step %} **Create a client** Browse to **Clients** (in the left-hand navigation) and select **Create client** to open the client configuration wizard.

{% endstep %} {% step %} **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**.

{% endstep %} {% step %} **Activate implicit flow** Click the check box to activate **Implicit flow** and then click **Next.**

{% endstep %} {% step %} **Add 3 Redirect URLs** They should have the pattern: * `https://ocff--.firebaseapp.com/__/auth/handler` * `https://ocff--.web.app/__/auth/handler` * `https://pick--.web.app/__/auth/handler` Then, click **Save** to create the client. Save the **Client ID** as it must be supplied to us via API.

{% endstep %} {% endstepper %} ## **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**. {% hint style="info" %} In the following screenshot, the administrator role is created. This has to be done for SUPERVISOR and FULFILLER similarly. {% endhint %}

## **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 \-dedicated entry:

Then, select **Configure a new mapper.**

Select **Group Membership***.*

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

{% hint style="info" %} Now, all groups of a user are put into the token. fulfillmenttools leverages this to identify which user is allowed to access a facility in fulfillmenttools. {% endhint %} ## **Disable "Full scope allowed"** In the Keycloak administration console, select **Clients** and the **Client scopes** tab. Select the \-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:

{% hint style="info" %} If the OpenID scope is unavailable on the Keycloak instance, create it in the admin console (Client Scopes in the left navigation pane). {% endhint %} ## 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: ```http POST https://{projectId}.api.fulfillmenttools.com/api/configurations/oidcproviders ``` ```json { "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}" ] } ] } ```