> 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/client-credential-flow-with-external-idp.md). # Client-Credential-Flow with external IDP This page explains how to connect an external Identity Provider (IDP) using the OAuth 2.0 client-credential flow. fulfillmenttools creates an internal OpenID Connect (OIDC) service user based on the `appid` in the access token. This service user is not listed in user endpoints or Backoffice, which lists human users. OIDC service users can be assigned any roles available to human users. ## Overview * **Flow**: `OAuth 2.0 client-credential` (`grant_type=client_credentials`) * **Token requirements**: * The token must be a JSON Web Token (JWT) signed with RS256 by the IDP. * The token must include the `iss`, `aud`, `exp`, and `appid` claims. * The `appid` uniquely identifies the service user in fulfillmenttools. * **Visibility**: Service users are not visible in regular user listings. * **Roles**: * Platform roles are assigned to service users by their external identifier (`appid`). * Service users support any role defined in fulfillmenttools. The login fails if a specified role doesn't exist. ## Rate limits * **Default**: 2000 logins per minute per tenant. * Exceeding the limit returns a `429` status code or a similar throttle response. * The limit can be increased upon request via support. ## Recommendations * It's recommended to reuse access tokens until they expire, based on the `exp` claim, to avoid unnecessary logins. * A single token should be used across concurrent requests where appropriate. * Implement exponential backoff and jitter on retries. ## Security and lifecycle * **Token lifetime**: The default lifetime in Entra ID is approximately one hour. Avoid shortening this to prevent frequent logins. * **Key rollover**: Microsoft rotates signing keys; the platform uses a JSON Web Key Set (JWKS) to follow these rotations automatically. * **Secret hygiene**: It is recommended to use certificates over client secrets and rotate them regularly. * **Least privilege**: Use a dedicated client and app role only for the fulfillmenttools integration. ## Support To configure the audience and issuer, assign roles, or request a rate-limit increase, contact fulfillmenttools support. The request must include the `tenantId`, `issuer`, `audience`, and the client `appid`. ## How to guide {% hint style="success" %} #### Prerequisites * A fully configured external IDP. For an example, see [Configure Microsoft Entra ID](https://github.com/fulfillmenttools/documentation-developer/blob/master/connecting-to-fulfillmenttools/openid-connect/configure-microsoft-entra-id-azure-active-directory.md). * An OAuth application is configured within the IDP with a `client_id` and `client_secret` that's capable of the client-credential flow. {% endhint %} {% stepper %} {% step %} **Get an ID token from the IDP with cURL** ```shell # Variables TENANT_ID="{your-tenant-id}" CLIENT_ID="{your-client-app-id}" # 'fulfillmenttools-client' CLIENT_SECRET="{your-client-secret}" SCOPE="api://{api-app-id-or-uri}/.default" # from 'fulfillmenttools-api' # Request a token (OAuth 2.0 v2 endpoint) curl -sS -X POST "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=${CLIENT_ID}" \ -d "client_secret=${CLIENT_SECRET}" \ -d "grant_type=client_credentials" \ -d "scope=${SCOPE}" ``` {% endstep %} {% step %} **Get an identity platform token** You'll need to replace `{your-api-key}` with your API key for fulfillmenttools. You'll also need to replace the `{insert-id-token}` and `{insert-oidc-provider-id}` with the relevant information. 
curl -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key={your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "requestUri": "http://localhost",
    "postBody": "id_token={insert-id-token}&providerId=oidc.external.{insert-oidc-provider-id}",
    "returnRefreshToken": true,
    "sessionId": null,
    "idToken": null,
    "returnSecureToken": true,
    "returnIdpCredential": null,
    "tenantId": null,
    "pendingToken": null
  }'
{% endstep %} {% step %} **Use the identity platform token to call fulfillmenttools APIs** Replace `{access-token}` with the token response you received in step 2, and replace `{projectId}` with your tenant name. ```shell ACCESS_TOKEN="{access-token}" FFT_BASE_URL="https://ocff-{projectId}.api.fulfillmenttools.com/api/" curl -sS -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ "${FFT_BASE_URL}/users" ``` {% endstep %} {% endstepper %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fulfillmenttools.com/documentation/integrations/openid-connect/client-credential-flow-with-external-idp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.