# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/integrations/openid-connect.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.