OpenID Connect role management modes

By default, fulfillmenttools uses OpenID Connect (OIDC) for authentication and to synchronize authorization information, such as roles and facility assignments.

For enterprise environments where authorization is managed separately from the Identity Provider (IdP), fulfillmenttools supports multiple role management modes.

This behavior is configured per OIDC provider using the field:

{
  ...
  "roleManagementMode": "IDP_MANAGED"
  ...
}

Supported values:

• IDP_MANAGED (default)

• IDP_IDENTITY_ONLY (not recommended)

IDP_MANAGED (default)

This is the recommended mode.

In this mode, the Identity Provider is the single source of truth for:

• User lifecycle

• Authentication

• Application roles

• Facility assignments

{
  "roleManagementMode": "IDP_MANAGED"
}

Log in behavior

When a user signs in:

1. User identity is synchronized from the IdP

2. Roles are synchronized from the IdP

3. Facility assignments are synchronized from the configured groups

4. Existing role and facility assignments in fulfillmenttools are overwritten

Advantages

• Single source of truth

• No duplicate permission administration

• Simpler compliance and auditing

• Recommended by fulfillmenttools

Configuration

{
  "name": "Microsoft Entra ID",
  "status": "ACTIVE",
  "roleManagementMode": "IDP_MANAGED",
  ...
}

IDP_IDENTITY_ONLY

We recommend only using this mode when roles and facility assignments can't practically be managed in the Identity Provider.

In this mode, the Identity Provider is responsible only for:

• Authentication

• User identity

• User lifecycle

Roles and facility assignments are managed directly in fulfillmenttools.

{
  "roleManagementMode": "IDP_IDENTITY_ONLY"
}

Log in behavior

When a user signs in:

1. User identity is synchronized from the IdP

2. User is created automatically if it doesn't already exist

3. Existing fulfillmenttools roles remain unchanged

4. Existing fulfillmenttools facility assignments remain unchanged

5. Groups received from the IdP are ignored for authorization purposes

Configuration

{
  "name": "Microsoft Entra ID",
  "status": "ACTIVE",
  "roleManagementMode": "IDP_IDENTITY_ONLY",
  ...
}

Managing roles and facilities in fulfillmenttools

When an OIDC provider is configured with IDP_IDENTITY_ONLY, roles and facility assignments can be managed through fulfillmenttools APIs.

PATCH /api/users/{userId}
{
  "version": 6,
  "actions": [
    {
      "action": "ModifyUser",
      "id": "Fl2cxHw9tOQ19OnrcuXyO1KD2il1",
      "assignedRoles": [
        {
          "ref": "FULFILLER",
          "context": [
            {
              "type": "FACILITY",
              "values": [
                "019eeeb1-0f58-7188-989d-eba22fe59669"
              ]
            }
          ]
        }
      ]
    }
  ]
}

fulfillmenttools doesn't emit user role or facility provisioning events that can automatically synchronize external authorization systems. If authorization is managed within fulfillmenttools, provisioning and updates must be handled explicitly through the API.

Administrator role restriction

For OIDC users, the ADMINISTRATOR role remains managed by the Identity Provider.

It can't be assigned or removed locally through fulfillmenttools APIs or Backoffice.