Account provisioning keeps application users and groups aligned with a central identity system. Open WebUI supports SCIM requests to create accounts, synchronize group membership, and mark a provisioned account inactive without deleting its history.
SCIM is enabled through deployment environment variables rather than an admin-panel switch. A direct protocol client can test the endpoint before an identity-provider administrator connects its provisioning application. Sign-in still uses a separate authentication method, such as the existing Corporate SSO OIDC integration.
The SCIM bearer token grants account and group administration rights. A retained local administrator provides recovery if provisioning or sign-in fails. An inactive SCIM account becomes Pending; that state must not be treated as proof that every existing session has been revoked.
Steps to enable SCIM provisioning in Open WebUI:
- Identify the SCIM endpoint and the existing sign-in provider identifier.
Open WebUI URL: https://openwebui.example.com SCIM base URL: https://openwebui.example.com/api/v1/scim/v2/ OIDC display label: Corporate SSO SCIM auth provider: oidc
The generic OIDC integration uses the internal identifier oidc even when OAUTH_PROVIDER_NAME displays Corporate SSO. SCIM_AUTH_PROVIDER uses that identifier, not the button label. A stable identity-provider externalId identifies later SCIM updates. A lookup by externalId alone does not test Corporate SSO sign-in or account linking.
Related: How to enable SSO in Open WebUI - Back up the active Compose definition before changing its service environment.
$ cp -p compose.yaml compose.yaml.before-scim
The existing deployment must already have a working local administrator and trusted HTTPS. The commands run in its current Compose project directory, using the existing .env from How to run Open WebUI with Docker Compose. Recreating the service briefly interrupts connections. The image, data volume, existing environment file and WEBUI_SECRET_KEY remain part of the original service definition.
Related: How to run Open WebUI with Docker Compose - Generate a new SCIM token into an owner-only file.
$ ( umask 077 set -C printf 'OPEN_WEBUI_SCIM_TOKEN=%s\n' "$(openssl rand -hex 32)" > open-webui-scim.env )
The token must stay out of source control, terminal output, process arguments and screenshots. The subshell prevents overwriting an existing token file and writes one definition instead of appending duplicates. An existing SCIM deployment keeps its current token; generating a replacement requires coordinated rotation at the identity provider.
- Add the SCIM environment entries to the existing open-webui service.
- compose.yaml
services: open-webui: environment: SCIM_ENABLED: "true" SCIM_TOKEN: "${OPEN_WEBUI_SCIM_TOKEN:?SCIM token file required}" SCIM_AUTH_PROVIDER: "oidc"
This fragment extends the existing service rather than replacing its image, ports or volumes. A service-level env_file does not supply Compose's ${...} interpolation; the next commands load the original .env first and open-webui-scim.env second with --env-file. Other deployments retain their existing interpolation files, project name and Compose file options alongside the SCIM file. An exported OPEN_WEBUI_SCIM_TOKEN takes precedence over the file.
An empty or incorrect provider identifier breaks externalId storage or account matching. The provider identifier must remain stable after provisioning starts.
- Validate Compose with the existing environment and SCIM token files.
$ docker compose --env-file .env --env-file open-webui-scim.env config --quiet
A successful check produces no output. Omitting --quiet can print the resolved secret.
- Enable SCIM by recreating the service with both environment files.
$ docker compose --env-file .env --env-file open-webui-scim.env up -d --force-recreate --wait open-webui
A plain restart does not load changed container environment variables. Restoring compose.yaml.before-scim and recreating the service reverses this configuration change without deleting the data volume.
- Create a protected curl configuration containing the SCIM authorization header.
$ ( umask 077 set -C . ./open-webui-scim.env printf 'header = "Authorization: Bearer %s"\n' "$OPEN_WEBUI_SCIM_TOKEN" > open-webui-scim.curl )
The generated environment file is trusted local input. curl reads the header from this protected file so the token does not appear in command arguments or shell history. Both secret files require the same protection.
- Check that a request without the bearer token is rejected.
$ curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \ https://openwebui.example.com/api/v1/scim/v2/Users 401
- List users with the protected SCIM credentials.
$ curl --config ./open-webui-scim.curl --fail-with-body --silent --show-error \ https://openwebui.example.com/api/v1/scim/v2/Users
A successful response contains the SCIM ListResponse schema and a Resources array. A 401 indicates missing or invalid bearer credentials. A 404 can indicate a missing /api/v1 prefix. Which existing accounts appear depends on the Open WebUI version; a listing is only an authentication check.
- Provision a disposable standard user through the SCIM endpoint.
$ curl --config ./open-webui-scim.curl --fail-with-body --silent --show-error \ -H "Content-Type: application/scim+json" \ --data '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "morgan.identity@example.com", "externalId": "idp-user-1001", "displayName": "Morgan Identity", "name": {"givenName": "Morgan", "familyName": "Identity"}, "emails": [{"value": "morgan.identity@example.com", "primary": true}], "active": true }' \ https://openwebui.example.com/api/v1/scim/v2/Users
The address must be unique and valid. idp-user-1001 stands for the stable identity-provider user ID; it is not an email-based linking rule. The response's id is the Open WebUI user ID used in the following requests.
- Assign the returned Open WebUI user ID to a shell variable.
$ SCIM_USER_ID='<open-webui-user-id>'
- Push a group containing the provisioned user.
$ curl --config ./open-webui-scim.curl --fail-with-body --silent --show-error \ -H "Content-Type: application/scim+json" \ --data @- https://openwebui.example.com/api/v1/scim/v2/Groups <<EOF { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Support Reviewers", "externalId": "idp-group-2001", "members": [{"value": "$SCIM_USER_ID"}] } EOF
SCIM synchronizes membership. Resource permissions remain an Open WebUI RBAC setting.
Related: How to create an RBAC group in Open WebUIThe next request changes the test user's role to Pending and interrupts normal access. An active=false response proves the provisioning state, not universal session revocation. Immediate offboarding also requires the session controls and access checks in How to disable a user in Open WebUI.
- Deactivate only the disposable test user through SCIM.
$ curl --config ./open-webui-scim.curl --fail-with-body --silent --show-error \ -X PATCH -H "Content-Type: application/scim+json" \ --data '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{"op": "replace", "path": "active", "value": false}] }' \ "https://openwebui.example.com/api/v1/scim/v2/Users/$SCIM_USER_ID"
- Confirm that an external-ID lookup returns the same inactive user.
$ curl --config ./open-webui-scim.curl --fail-with-body --silent --show-error \ --get --data-urlencode 'filter=externalId eq "idp-user-1001"' \ https://openwebui.example.com/api/v1/scim/v2/Users
The response must have totalResults equal to 1, the same id, externalId equal to idp-user-1001, and active equal to false. This verifies stored provisioning state under the configured provider.
- Open the user menu in the retained administrator session.

- Select Admin Panel.
The panel opens on Users.
- Confirm that Morgan Identity appears as Pending in the Users table.
The local administrator remains Admin. The inactive user record is retained.
- Open the Groups tab.

- Open Support Reviewers.

- Select Users in the group editor to confirm the provisioned membership.
The group contains Morgan Identity after the SCIM user and group requests, and the external-ID query returns the stored inactive account. The identity-provider administrator can now configure its connector with the same SCIM base URL and bearer token through a secure handoff; connector-specific setup remains outside this direct-request test.