API documentationIncident ManagementFeedback
Edit

Client-Credential-Flow with external IDP

This page explains how to connect an external IDP using OAuth 2.0 Client‑Credentials. The platform creates an internal OIDC service user based on the appid in the access token. This service user is not listed in user endpoints or Backoffice (those list human users). OIDC service users can be assigned any roles available to human users.

Overview

  • Flow: OAuth 2.0 Client‑Credentials (grant_type=client_credentials)

  • Token requirements:

    • Must be a JWT signed with RS256 by your IDP.

    • Must include iss, aud, exp, and appid claims

    • appid uniquely identifies the service user in fulfillmenttools

  • Visibility: Service users are not visible in regular user listings

  • Roles:

    • Assign platform roles to service users by their external identifier (appid)

    • Supports any role defined in fulfillmenttools; login fails if the specified role does not exist.

Rate limits

  • Default: 2000 logins per minute per tenant

  • Exceeding the limit returns 429 or similar throttle responses

  • Can be increased on request via support

Recommendations:

  • Reuse access tokens until expiry (exp) to avoid unnecessary logins

  • Use a single token across concurrent requests where appropriate

  • Implement exponential backoff and jitter on retries

Security and lifecycle

  • Token lifetime: Entra ID default ~1 hour; avoid shortening to prevent frequent logins

  • Key rollover: Microsoft rotates signing keys; platform uses JWKS to follow rotations

  • Secret hygiene: Prefer certificates over client secrets; rotate regularly

  • Least privilege: Use a dedicated client and app role only for fulfillmenttools

Support

For audience/issuer configuration, role assignment, or rate‑limit increases, contact fulfillmenttools support and include your tenantId, issuer, audience, and the client appid.

How-To:

Prerequisites

Get an id token the IDP with cURL

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

Get an identity platform token

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
  }'

Use the identity platform token to call fulfillmenttools APIs

ACCESS_TOKEN="<paste-access-token>"
FFT_BASE_URL="https://{your-tenant}.api.fulfillmenttools.com/api/"

curl -sS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "${FFT_BASE_URL}/api/users"

Last updated