> For the complete documentation index, see [llms.txt](https://docs.fulfillmenttools.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fulfillmenttools.com/documentation/integrations/openid-connect.md).

# OpenID Connect (OIDC)

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

## SSO protocols

OpenID Connect (OIDC) is an interoperable authentication protocol based on the OAuth 2.0 framework.

SAML (Security Assertion Markup Language) is an SSO and federated authentication protocol. It exchanges XML-based assertions.

SAML and OIDC are distinct protocols. They're not interchangeable configuration formats.

fulfillmenttools configures external IdP integrations through OIDC and doesn't support direct SAML provider configuration.

If your IdP supports only SAML, use an OIDC-capable identity broker or OIDC-enabled IdP endpoint before configuring fulfillmenttools. You can't configure SAML metadata, certificates, or assertions directly in fulfillmenttools.

General OIDC documentation is available in the official [OpenID Connect documentation](https://openid.net/developers/how-connect-works/). Most major IdPs support the OIDC protocol, including Microsoft Entra ID (formerly Azure Active Directory), Auth0, and Keycloak.

All IdPs require you to create 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. Also, configure groups and roles in the IdP to enrich the authentication token with the required 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://ocff-{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 %}

{% hint style="danger" %}

#### Important: The application must not be re-signed

Re-signing changes the application's certificate fingerprint (SHA-1/SHA-256), which is used for SSO authentication. As a result, SSO login may fail with errors such as `INVALID_CERT_HASH`.

Always deploy the original APK signed with the approved certificate.

If the app is re-signed by an MDM, wrapping solution, or deployment process, SSO functionality can't be guaranteed.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.