> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM 2.0 Provisioning

> Automate user and group lifecycle management with SCIM 2.0 protocol

Open WebUI supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user and group provisioning from enterprise identity providers like Okta, Azure AD, and Google Workspace.

<Note>
  This is an **experimental implementation** and may not fully comply with SCIM 2.0 standards. The API is subject to change in future releases.
</Note>

## Overview

SCIM 2.0 enables:

* **Automatic User Provisioning** - Create users when assigned to the application
* **User Deprovisioning** - Disable/delete users when unassigned
* **Group Sync** - Automatically create and manage groups with members
* **Profile Updates** - Keep user information synchronized
* **Lifecycle Management** - Handle user state transitions (active/inactive)

## Configuration

### Enable SCIM

Set these environment variables:

```bash theme={null}
# Enable SCIM 2.0 endpoint
ENABLE_SCIM=true

# SCIM authentication token (generate a strong random token)
SCIM_TOKEN=your-secure-random-token-here

# OAuth provider for account linking (required)
SCIM_AUTH_PROVIDER=microsoft  # or 'oidc', 'google', etc.
```

<Warning>
  **SCIM\_AUTH\_PROVIDER is required** - This links SCIM-provisioned users to OAuth/SSO accounts.
  Set it to your OAuth provider name: `microsoft`, `google`, `github`, or `oidc`.
</Warning>

### Generate SCIM Token

Create a strong, random token for SCIM authentication:

```bash theme={null}
# Generate a secure token
openssl rand -base64 32

# Or use Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

## SCIM Endpoint

The SCIM v2 endpoints are available at:

```
https://your-openwebui-domain/api/v1/scim/v2/
```

### Authentication

All SCIM requests require Bearer token authentication:

```bash theme={null}
Authorization: Bearer your-scim-token-here
```

### Supported Endpoints

| Endpoint                 | Methods                       | Description               |
| ------------------------ | ----------------------------- | ------------------------- |
| `/ServiceProviderConfig` | GET                           | SCIM service capabilities |
| `/ResourceTypes`         | GET                           | Supported resource types  |
| `/Schemas`               | GET                           | SCIM schemas              |
| `/Users`                 | GET, POST, PUT, PATCH, DELETE | User management           |
| `/Groups`                | GET, POST, PUT, PATCH, DELETE | Group management          |

## Identity Provider Configuration

### Okta

1. **Add Application Integration**:
   * Applications → Create App Integration
   * Select "SCIM 2.0 Test App (Header Auth)"

2. **Configure SCIM**:
   * SCIM Base URL: `https://your-domain.com/api/v1/scim/v2`
   * Authentication Mode: HTTP Header
   * Authorization: `Bearer your-scim-token`

3. **Enable Features**:
   * Create Users
   * Update User Attributes
   * Deactivate Users
   * Sync Password (optional)
   * Import Groups

4. **Attribute Mapping**:
   ```
   userName    → email
   email       → email
   givenName   → name.givenName
   familyName  → name.familyName
   displayName → displayName
   active      → active
   ```

5. **Set SCIM\_AUTH\_PROVIDER**:
   ```bash theme={null}
   SCIM_AUTH_PROVIDER=oidc  # If using Okta OAuth
   ```

### Azure AD (Microsoft Entra ID)

1. **Enterprise Applications**:
   * Azure Active Directory → Enterprise applications
   * New application → Create your own application
   * Select "Integrate any other application you don't find in the gallery"

2. **Provisioning Configuration**:
   * Provisioning → Automatic
   * Tenant URL: `https://your-domain.com/api/v1/scim/v2`
   * Secret Token: `your-scim-token`
   * Test Connection

3. **Mappings**:
   * Provision Azure Active Directory Users:
     ```
     userPrincipalName → userName
     mail → emails[type eq "work"].value
     displayName → displayName
     givenName → name.givenName
     surname → name.familyName
     accountEnabled → active
     ```

4. **Provision Groups** (optional):
   * Enable group provisioning
   * Map `displayName` → `displayName`
   * Map `members` → `members`

5. **Set SCIM\_AUTH\_PROVIDER**:
   ```bash theme={null}
   SCIM_AUTH_PROVIDER=microsoft
   ```

### Google Workspace

1. **Custom SAML/SCIM App**:
   * Admin Console → Apps → Web and mobile apps
   * Add custom SAML app or SCIM app

2. **SCIM Configuration**:
   * SCIM Base URL: `https://your-domain.com/api/v1/scim/v2`
   * Authorization: Bearer Token
   * Access Token: `your-scim-token`

3. **Attribute Mapping**:
   ```
   Primary Email → userName
   First Name → name.givenName
   Last Name → name.familyName
   Suspended → active (inverted)
   ```

4. **Set SCIM\_AUTH\_PROVIDER**:
   ```bash theme={null}
   SCIM_AUTH_PROVIDER=google
   ```

## User Provisioning Flow

### 1. User Assignment

When a user is assigned to the app in your IdP:

```http theme={null}
POST /api/v1/scim/v2/Users
Authorization: Bearer your-scim-token
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john.doe@company.com",
  "externalId": "00u1234567890abcdef",
  "name": {
    "givenName": "John",
    "familyName": "Doe",
    "formatted": "John Doe"
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "john.doe@company.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true
}
```

**Open WebUI creates**:

* User account with `userName` as email
* Links `externalId` to OAuth provider (via `SCIM_AUTH_PROVIDER`)
* Sets role to `user` if `active: true`, `pending` if `active: false`

### 2. User Update

Profile changes are synchronized:

```http theme={null}
PATCH /api/v1/scim/v2/Users/{userId}
Authorization: Bearer your-scim-token
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "John D. Doe"
    },
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}
```

### 3. User Deactivation

When a user is unassigned or suspended:

```http theme={null}
DELETE /api/v1/scim/v2/Users/{userId}
Authorization: Bearer your-scim-token
```

User account is **deleted** from Open WebUI.

## Group Provisioning

### Create Group with Members

```http theme={null}
POST /api/v1/scim/v2/Groups
Authorization: Bearer your-scim-token
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    {
      "value": "user-id-1",
      "display": "John Doe"
    },
    {
      "value": "user-id-2",
      "display": "Jane Smith"
    }
  ]
}
```

### Add Member to Group

```http theme={null}
PATCH /api/v1/scim/v2/Groups/{groupId}
Authorization: Bearer your-scim-token
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "user-id-3"
        }
      ]
    }
  ]
}
```

### Remove Member from Group

```http theme={null}
PATCH /api/v1/scim/v2/Groups/{groupId}
Authorization: Bearer your-scim-token
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"user-id-3\"]"
    }
  ]
}
```

## Docker Compose Example

```yaml theme={null}
version: '3'

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      # SCIM Configuration
      - ENABLE_SCIM=true
      - SCIM_TOKEN=${SCIM_TOKEN}  # From .env file
      - SCIM_AUTH_PROVIDER=microsoft  # or oidc, google, etc.
      
      # OAuth Configuration (must match SCIM_AUTH_PROVIDER)
      - MICROSOFT_CLIENT_ID=${MICROSOFT_CLIENT_ID}
      - MICROSOFT_CLIENT_SECRET=${MICROSOFT_CLIENT_SECRET}
      - MICROSOFT_CLIENT_TENANT_ID=${MICROSOFT_TENANT_ID}
    volumes:
      - open-webui:/app/backend/data
    restart: always

volumes:
  open-webui:
```

## Troubleshooting

### SCIM Token Authentication Fails

**Check**:

* `ENABLE_SCIM=true` is set
* `SCIM_TOKEN` matches the token configured in IdP
* Authorization header: `Authorization: Bearer your-token`

### Users Not Created

**Check**:

* SCIM test connection succeeds in IdP
* User attribute mappings are correct (especially `userName` and `emails`)
* `SCIM_AUTH_PROVIDER` is set correctly

### ExternalId Not Stored

**Problem**: User created but SSO login fails

**Solution**: Set `SCIM_AUTH_PROVIDER` to match your OAuth provider:

```bash theme={null}
SCIM_AUTH_PROVIDER=microsoft  # For Azure AD
SCIM_AUTH_PROVIDER=google     # For Google Workspace
SCIM_AUTH_PROVIDER=oidc       # For generic OIDC
```

### Group Sync Issues

**Check**:

* Group provisioning is enabled in IdP
* Member IDs in SCIM requests match user IDs in Open WebUI
* Admin user exists for group creation

## Security Considerations

<Warning>
  **SCIM Security Best Practices:**

  1. **Strong Token** - Use cryptographically random 32+ character tokens
  2. **HTTPS Only** - Never expose SCIM endpoints over HTTP
  3. **IP Restrictions** - Limit SCIM access to IdP IP ranges
  4. **Token Rotation** - Rotate SCIM tokens periodically
  5. **Monitor Access** - Log and alert on SCIM authentication failures
  6. **Rate Limiting** - Implement rate limits on SCIM endpoints
</Warning>

## Implementation Details

* SCIM Router: `backend/open_webui/routers/scim.py`
* Supports SCIM 2.0 core schemas (RFC 7643)
* Pagination with `startIndex` and `count`
* Filtering: `userName eq "user@domain.com"`, `externalId eq "id"`
* Partial updates via PATCH operations

## Next Steps

* [LDAP Integration](/enterprise/ldap-active-directory) - Directory services authentication
* [RBAC](/enterprise/rbac) - Configure role-based permissions
* [OAuth SSO](/features/sso) - Set up single sign-on