> 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/openid-connect-role-management-modes.md).

# 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:

```json
{
  ...
  "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

```json
{
  "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

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

## IDP\_IDENTITY\_ONLY

{% hint style="warning" %}
We recommend only using this mode when roles and facility assignments can't practically be managed in the Identity Provider.
{% endhint %}

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

* Authentication
* User identity
* User lifecycle

Roles and facility assignments are managed directly in fulfillmenttools.

```json
{
  "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

```json
{
  "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.

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

{% hint style="info" %}
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.
{% endhint %}

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


---

# 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/openid-connect-role-management-modes.md?ask=<question>&goal=<endgoal>
```

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