From 0f96a4a0e7799dcbfa22c9a94b8919234e0278bb Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 00:57:57 +0200 Subject: [PATCH 01/14] test --- .github/workflows/gh-pages.yml | 3 +++ .vscode/settings.json | 11 +++++++++++ docusaurus.config.ts | 4 ++-- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2a970168..868b89b2 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -36,6 +36,9 @@ jobs: - name: Install dependencies run: npm ci - name: Build + env: + BASE_URL: ${{ vars.BASE_URL }} + SITE_URL: ${{ vars.SITE_URL }} run: npm run build - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/.vscode/settings.json b/.vscode/settings.json index 1868959f..d92c657d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,5 +3,16 @@ "no-inline-html": false, "link-image-reference-definitions": false, "fenced-code-language": false + }, + "files.exclude": { + "**/.git": true, + "**/.svn": true, + "**/.hg": true, + "**/.DS_Store": true, + "**/Thumbs.db": true, + "**/.retool_types/**": true, + "**/*tsconfig.json": true, + ".cache": true, + "retool.config.json": true } } diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 914e09e1..8ddff9da 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -9,10 +9,10 @@ const config: Config = { favicon: "images/favicon.png", // Set the production url of your site here - url: "https://openwebui.com", + url: process.env.SITE_URL || "https://openwebui.com", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: "/", + baseUrl: process.env.BASE_URL || "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. From 43d13ae2c3b645021285ab0f2528c360fbcfa320 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:07:10 +0200 Subject: [PATCH 02/14] Update docusaurus.config.ts --- docusaurus.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8ddff9da..ba3304d4 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -12,7 +12,7 @@ const config: Config = { url: process.env.SITE_URL || "https://openwebui.com", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: process.env.BASE_URL || "/", + baseUrl: process.env.BASE_URL || "/docs/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. From 0116340816604ae55f9f38732d0ce411602ad7fd Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:17:33 +0200 Subject: [PATCH 03/14] add scim env documentation --- docs/getting-started/env-configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/getting-started/env-configuration.md b/docs/getting-started/env-configuration.md index 000f02b4..3abf6995 100644 --- a/docs/getting-started/env-configuration.md +++ b/docs/getting-started/env-configuration.md @@ -2922,6 +2922,22 @@ If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture c - Description: Specifies the LDAP attribute that contains the user's group memberships. `memberOf` is a standard attribute for this purpose in Active Directory environments. - Persistence: This environment variable is a `PersistentConfig` variable. +## SCIM + +#### `SCIM_ENABLED` + +- Type: `bool` +- Default: `False` +- Description: Enables or disables SCIM 2.0 (System for Cross-domain Identity Management) support for automated user and group provisioning from identity providers like Okta, Azure AD, and Google Workspace. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `SCIM_TOKEN` + +- Type: `str` +- Default: `""` +- Description: Sets the bearer token for SCIM authentication. This token must be provided by identity providers when making SCIM API requests. Generate a secure random token (e.g., using `openssl rand -base64 32`) and configure it in both Open WebUI and your identity provider. +- Persistence: This environment variable is a `PersistentConfig` variable. + ## User Permissions ### Chat Permissions From 57a553118c65682b9848788d9657acb966522b3f Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:23:20 +0200 Subject: [PATCH 04/14] Create scim.mdx --- docs/features/scim.mdx | 199 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/features/scim.mdx diff --git a/docs/features/scim.mdx b/docs/features/scim.mdx new file mode 100644 index 00000000..1270669f --- /dev/null +++ b/docs/features/scim.mdx @@ -0,0 +1,199 @@ +--- +sidebar_position: 20 +title: "🔐 SCIM 2.0: Automated User Provisioning" +--- + +# SCIM 2.0 Support + +Open WebUI supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user and group provisioning from identity providers like Okta, Azure AD, and Google Workspace. + +## Overview + +SCIM is an open standard that allows for the automation of user provisioning. When enabled, your identity provider can automatically: +- Create users in Open WebUI when they're added to your organization +- Update user information when changes are made +- Deactivate users when they're removed from your organization +- Manage group memberships + +## Configuration + +SCIM is configured entirely through environment variables. There is no UI configuration for SCIM settings. + +### Environment Variables + +Configure SCIM by setting these environment variables: + +- **`SCIM_ENABLED`**: Set to `true` to enable SCIM support (default: `false`) +- **`SCIM_TOKEN`**: The bearer token for SCIM authentication (required when SCIM is enabled) + +:::warning Security Note +The SCIM token should be a secure, randomly generated string. You can generate one using: +```bash +openssl rand -base64 32 +``` +Keep this token secure as it provides access to user management operations. +::: + +### Example Configuration + +```bash +# Enable SCIM +export SCIM_ENABLED=true + +# Set a secure token (replace with your own generated token) +export SCIM_TOKEN="your-secure-token-here" +``` + +## SCIM API Configuration + +When configuring your identity provider, use the following settings: + +- **SCIM Base URL**: `/api/v1/scim/v2/` +- **Authentication**: Bearer Token +- **Token**: `Bearer ` + +### Example for Popular Identity Providers + +#### Okta +1. In Okta, add the SCIM application +2. Set the SCIM connector base URL to: `https://your-domain.com/api/v1/scim/v2/` +3. Set authentication to "HTTP Header" +4. Add Authorization header with value: `Bearer your-scim-token` + +#### Azure AD / Entra ID +1. In Azure AD, configure provisioning for your enterprise application +2. Set the Tenant URL to: `https://your-domain.com/api/v1/scim/v2/` +3. Set the Secret Token to: `your-scim-token` + +#### Google Workspace +1. In Google Admin, configure SCIM provisioning +2. Set the SCIM endpoint URL to: `https://your-domain.com/api/v1/scim/v2/` +3. Set the access token to: `your-scim-token` + +## Supported SCIM Operations + +Open WebUI's SCIM implementation supports the following operations: + +### User Operations +- **Create User** (`POST /Users`): Create a new user account +- **Get User** (`GET /Users/{id}`): Retrieve user information +- **Update User** (`PUT /Users/{id}`, `PATCH /Users/{id}`): Update user attributes +- **Delete User** (`DELETE /Users/{id}`): Deactivate a user account +- **List Users** (`GET /Users`): List all users with filtering support + +### Group Operations +- **Create Group** (`POST /Groups`): Create a new group +- **Get Group** (`GET /Groups/{id}`): Retrieve group information +- **Update Group** (`PUT /Groups/{id}`, `PATCH /Groups/{id}`): Update group membership +- **Delete Group** (`DELETE /Groups/{id}`): Remove a group +- **List Groups** (`GET /Groups`): List all groups with filtering support + +### Supported Attributes + +#### User Attributes +- `userName`: The user's email address (required, unique) +- `name.givenName`: First name +- `name.familyName`: Last name +- `emails`: Email addresses +- `active`: User status (active/inactive) +- `externalId`: External identifier from the identity provider + +#### Group Attributes +- `displayName`: Group name (required) +- `members`: Array of user members +- `externalId`: External identifier from the identity provider + +## Filtering Support + +The SCIM API supports filtering for both users and groups: + +``` +GET /api/v1/scim/v2/Users?filter=userName eq "user@example.com" +GET /api/v1/scim/v2/Groups?filter=displayName eq "Engineering" +``` + +Supported filter operators: +- `eq`: Equals +- `ne`: Not equals +- `co`: Contains +- `sw`: Starts with +- `ew`: Ends with +- `pr`: Present (has value) +- `gt`: Greater than +- `ge`: Greater than or equal +- `lt`: Less than +- `le`: Less than or equal + +## Troubleshooting + +### Common Issues + +1. **401 Unauthorized Errors** + - Verify that `SCIM_ENABLED` is set to `true` + - Check that the bearer token in your identity provider matches `SCIM_TOKEN` + - Ensure the Authorization header format is: `Bearer ` + +2. **404 Not Found Errors** + - Verify the SCIM base URL ends with `/api/v1/scim/v2/` + - Check that the path includes the `/api/v1` prefix + +3. **User Creation Failures** + - Ensure the `userName` field contains a valid email address + - Check that the email is not already in use + +### Testing SCIM Endpoints + +You can test SCIM endpoints using curl: + +```bash +# Test authentication and list users +curl -H "Authorization: Bearer your-scim-token" \ + https://your-domain.com/api/v1/scim/v2/Users + +# Get a specific user +curl -H "Authorization: Bearer your-scim-token" \ + https://your-domain.com/api/v1/scim/v2/Users/user-id + +# Create a test user +curl -X POST \ + -H "Authorization: Bearer your-scim-token" \ + -H "Content-Type: application/scim+json" \ + -d '{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "test@example.com", + "name": { + "givenName": "Test", + "familyName": "User" + }, + "emails": [{ + "value": "test@example.com", + "primary": true + }], + "active": true + }' \ + https://your-domain.com/api/v1/scim/v2/Users +``` + +## Security Considerations + +1. **Use HTTPS**: Always use HTTPS in production to protect the bearer token +2. **Secure Token Storage**: Store the SCIM token securely and rotate it periodically +3. **IP Allowlisting**: Consider restricting SCIM API access to your identity provider's IP addresses +4. **Audit Logging**: SCIM operations are logged for security auditing + +## Limitations + +- Password management is not supported via SCIM (users authenticate via SSO) +- Custom schema extensions are not currently supported +- Bulk operations are not implemented +- ETags for resource versioning are not supported + +## Integration with SSO + +SCIM works best when combined with SSO (Single Sign-On). A typical setup includes: +1. SCIM for automated user provisioning +2. OAuth/SAML for user authentication + +This ensures users are automatically created and can immediately authenticate using their corporate credentials. + +For SSO configuration, see the [SSO documentation](/docs/features/sso). \ No newline at end of file From 3a83ea73f5ea6cea8c8946846462ada68143fb2b Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:27:25 +0200 Subject: [PATCH 05/14] Update scim.mdx --- docs/features/scim.mdx | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/features/scim.mdx b/docs/features/scim.mdx index 1270669f..fa44e2f0 100644 --- a/docs/features/scim.mdx +++ b/docs/features/scim.mdx @@ -60,15 +60,6 @@ When configuring your identity provider, use the following settings: 3. Set authentication to "HTTP Header" 4. Add Authorization header with value: `Bearer your-scim-token` -#### Azure AD / Entra ID -1. In Azure AD, configure provisioning for your enterprise application -2. Set the Tenant URL to: `https://your-domain.com/api/v1/scim/v2/` -3. Set the Secret Token to: `your-scim-token` - -#### Google Workspace -1. In Google Admin, configure SCIM provisioning -2. Set the SCIM endpoint URL to: `https://your-domain.com/api/v1/scim/v2/` -3. Set the access token to: `your-scim-token` ## Supported SCIM Operations @@ -183,7 +174,6 @@ curl -X POST \ ## Limitations -- Password management is not supported via SCIM (users authenticate via SSO) - Custom schema extensions are not currently supported - Bulk operations are not implemented - ETags for resource versioning are not supported @@ -192,7 +182,7 @@ curl -X POST \ SCIM works best when combined with SSO (Single Sign-On). A typical setup includes: 1. SCIM for automated user provisioning -2. OAuth/SAML for user authentication +2. OIDC for user authentication This ensures users are automatically created and can immediately authenticate using their corporate credentials. From 897e3fece0a00c07f477cf5f38f344224e575642 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:32:33 +0200 Subject: [PATCH 06/14] remove vscode --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b2d6de30..b5427b30 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,7 @@ .env.development.local .env.test.local .env.production.local - +.vscode npm-debug.log* yarn-debug.log* yarn-error.log* From 2e25ad400cd259084d85204a31f876898ec84da3 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Mon, 14 Jul 2025 01:33:06 +0200 Subject: [PATCH 07/14] Delete .vscode/settings.json --- .vscode/settings.json | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index d92c657d..00000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "markdownlint.config": { - "no-inline-html": false, - "link-image-reference-definitions": false, - "fenced-code-language": false - }, - "files.exclude": { - "**/.git": true, - "**/.svn": true, - "**/.hg": true, - "**/.DS_Store": true, - "**/Thumbs.db": true, - "**/.retool_types/**": true, - "**/*tsconfig.json": true, - ".cache": true, - "retool.config.json": true - } -} From 845a42890de45e6170cf1d138dfcfeeb5c139dd7 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:11:41 +0200 Subject: [PATCH 08/14] Update gh-pages.yml --- .github/workflows/gh-pages.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 868b89b2..2a970168 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -36,9 +36,6 @@ jobs: - name: Install dependencies run: npm ci - name: Build - env: - BASE_URL: ${{ vars.BASE_URL }} - SITE_URL: ${{ vars.SITE_URL }} run: npm run build - name: Upload artifact uses: actions/upload-pages-artifact@v3 From 83dca30512c54d183b8bc3b6341e7ed792b5c242 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:12:01 +0200 Subject: [PATCH 09/14] Update .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index b5427b30..2b462ce4 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,6 @@ .env.development.local .env.test.local .env.production.local -.vscode npm-debug.log* yarn-debug.log* yarn-error.log* From 8b83235c1991432c1f0b373dfc3b3e8af218e857 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:13:21 +0200 Subject: [PATCH 10/14] Update .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 2b462ce4..b2d6de30 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ .env.development.local .env.test.local .env.production.local + npm-debug.log* yarn-debug.log* yarn-error.log* From 33f2c812d3d161123e2d7d3ad7dd15f95a9fa3c1 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:13:56 +0200 Subject: [PATCH 11/14] Update docusaurus.config.ts --- docusaurus.config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index ba3304d4..bd8f0ba1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -9,10 +9,10 @@ const config: Config = { favicon: "images/favicon.png", // Set the production url of your site here - url: process.env.SITE_URL || "https://openwebui.com", + url: "https://openwebui.com", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: process.env.BASE_URL || "/docs/", + baseUrl: "/docs/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. From 8c3f1536d5eadedf303cbc85628759bd9b9b57e5 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:14:21 +0200 Subject: [PATCH 12/14] Update docusaurus.config.ts --- docusaurus.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index bd8f0ba1..914e09e1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -12,7 +12,7 @@ const config: Config = { url: "https://openwebui.com", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: "/docs/", + baseUrl: "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. From cd05dd24e60295b0c2ba93f747c131bbeeacda9b Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:19:49 +0200 Subject: [PATCH 13/14] Create settings.json --- .vscode/settings.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..5b1aca27 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,7 @@ +{ + "markdownlint.config": { + "no-inline-html": false, + "link-image-reference-definitions": false, + "fenced-code-language": false + } +} \ No newline at end of file From a3650b613a1d23bf7f631725bc1678099d4be582 Mon Sep 17 00:00:00 2001 From: Dieu <113346171+dieu-bis@users.noreply.github.com> Date: Wed, 13 Aug 2025 18:22:34 +0200 Subject: [PATCH 14/14] Update settings.json --- .vscode/settings.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 5b1aca27..1868959f 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,4 +4,4 @@ "link-image-reference-definitions": false, "fenced-code-language": false } -} \ No newline at end of file +}