# OpenID connect

fulfillmenttools supports the OpenID Connect (OIDC) protocol to integrate with external Identity Providers (IdPs).

General documentation regarding OIDC is available from the official [OpenID Connect documentation](https://openid.net/developers/how-connect-works/). The OIDC protocol is supported by most major IdPs, such as Microsoft Entra ID (formerly Azure Active Directory), Auth0, and Keycloak.

All IdPs require the creation of an OAuth application. This process provides the following data and credentials, which must be supplied to fulfillmenttools:

* `clientId`
* `clientSecret`
* `issuerUrl`

The IdP's documentation may specify additional required parameters. Furthermore, groups and roles must be configured within the IdP to enrich the authentication token with the necessary authorization information. Refer to the pages within this section for step-by-step guides for specific IdPs.

## Configure OIDC within fulfillmenttools

{% hint style="info" %}
For more details, see the [OIDC section in the API documentation](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/configurations/oidcproviders).
{% endhint %}

To register an OIDC provider with fulfillmenttools, use the following REST API endpoint:

```http
POST https://{projectId}.api.fulfillmenttools.com/api/configurations/oidcproviders
```

{% code title="OIDC request" %}

```json
{
    "name": "My Provider",
    "status": "ACTIVE",
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "issuer": "https://my-oidc-issuer.com",
    "customParameters": [],
    "assignedGroups": []
}
```

{% endcode %}

{% hint style="info" %}
Some IdPs require `customParameters` to enable Single Sign-On (SSO). Refer to the specific IdP's documentation for details.
{% endhint %}

## Map IdP groups to fulfillmenttools facilities

fulfillmenttools uses the IdP's groups feature to map users to facilities. In the fulfillmenttools OIDC configuration, these groups are mapped to facilities using the `assignedGroups` array. The mapping connects an IdP group ID to one or more fulfillmenttools facility references (`facilityRefs`).

```json
{
    ...
    "assignedGroups": [
        {
            "group": "idp-group-id",
            "facilityRefs": [
                "fft-facility-id"
            ]
        }
    ]
}
```

{% hint style="warning" %}
fulfillmenttools doesn't actively synchronize group assignments from the IdP. Any changes made to a user's group memberships in the IdP are applied the next time the user signs in to fulfillmenttools.
{% endhint %}