SCIM 2.0 Provisioning

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.

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

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:

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

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.

Generate SCIM Token

Create a strong, random token for SCIM authentication:

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

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

Add Application Integration:
- Applications → Create App Integration
- Select “SCIM 2.0 Test App (Header Auth)”
Configure SCIM:
- SCIM Base URL: https://your-domain.com/api/v1/scim/v2
- Authentication Mode: HTTP Header
- Authorization: Bearer your-scim-token
Enable Features:
- Create Users
- Update User Attributes
- Deactivate Users
- Sync Password (optional)
- Import Groups

Attribute Mapping:

userName    → email
email       → email
givenName   → name.givenName
familyName  → name.familyName
displayName → displayName
active      → active

Set SCIM_AUTH_PROVIDER:

SCIM_AUTH_PROVIDER=oidc  # If using Okta OAuth

Azure AD (Microsoft Entra ID)

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”
Provisioning Configuration:
- Provisioning → Automatic
- Tenant URL: https://your-domain.com/api/v1/scim/v2
- Secret Token: your-scim-token
- Test Connection

Mappings:

Provision Azure Active Directory Users:

userPrincipalName → userName
mail → emails[type eq "work"].value
displayName → displayName
givenName → name.givenName
surname → name.familyName
accountEnabled → active

Provision Groups (optional):
- Enable group provisioning
- Map displayName → displayName
- Map members → members
Set SCIM_AUTH_PROVIDER:
```
SCIM_AUTH_PROVIDER=microsoft
```

Google Workspace

Custom SAML/SCIM App:
- Admin Console → Apps → Web and mobile apps
- Add custom SAML app or SCIM app
SCIM Configuration:
- SCIM Base URL: https://your-domain.com/api/v1/scim/v2
- Authorization: Bearer Token
- Access Token: your-scim-token

Attribute Mapping:

Primary Email → userName
First Name → name.givenName
Last Name → name.familyName
Suspended → active (inverted)

Set SCIM_AUTH_PROVIDER:
```
SCIM_AUTH_PROVIDER=google
```

User Provisioning Flow

1. User Assignment

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

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:

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:

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

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

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

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

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:

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

SCIM Security Best Practices:

Strong Token - Use cryptographically random 32+ character tokens
HTTPS Only - Never expose SCIM endpoints over HTTP
IP Restrictions - Limit SCIM access to IdP IP ranges
Token Rotation - Rotate SCIM tokens periodically
Monitor Access - Log and alert on SCIM authentication failures
Rate Limiting - Implement rate limits on SCIM endpoints

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 - Directory services authentication
RBAC - Configure role-based permissions
OAuth SSO - Set up single sign-on

​Overview

​Configuration

​Enable SCIM

​Generate SCIM Token

​SCIM Endpoint

​Authentication

​Supported Endpoints

​Identity Provider Configuration

​Okta

​Azure AD (Microsoft Entra ID)

​Google Workspace

​User Provisioning Flow

​1. User Assignment

​2. User Update

​3. User Deactivation

​Group Provisioning

​Create Group with Members

​Add Member to Group

​Remove Member from Group

​Docker Compose Example

​Troubleshooting

​SCIM Token Authentication Fails

​Users Not Created

​ExternalId Not Stored

​Group Sync Issues

​Security Considerations

​Implementation Details

​Next Steps

Overview

Configuration

Enable SCIM

Generate SCIM Token

SCIM Endpoint

Authentication

Supported Endpoints

Identity Provider Configuration

Okta

Azure AD (Microsoft Entra ID)

Google Workspace

User Provisioning Flow

1. User Assignment

2. User Update

3. User Deactivation

Group Provisioning

Create Group with Members

Add Member to Group

Remove Member from Group

Docker Compose Example

Troubleshooting

SCIM Token Authentication Fails

Users Not Created

ExternalId Not Stored

Group Sync Issues

Security Considerations

Implementation Details

Next Steps