OpenID Connect (OIDC)

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. 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

For more details, see the OIDC section in the API documentation.

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

POST https://ocff-{projectId}.api.fulfillmenttools.com/api/configurations/oidcproviders

OIDC request

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

Some IdPs require customParameters to enable Single Sign-On (SSO). Refer to the specific IdP's documentation for details.

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).

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

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.

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.