diff --git a/docs/administration/scim/entra-id.mdx b/docs/administration/scim/entra-id.mdx
new file mode 100644
index 00000000..011d4a77
--- /dev/null
+++ b/docs/administration/scim/entra-id.mdx
@@ -0,0 +1,104 @@
+---
+title: Entra ID
+---
+
+
+
+## Create enterprise application
+
+Sign in to the Entra ID Admin Center Dashboard. Select **Enterprise applications** and click **New application**.
+
+
+
+Select **Create your own application**. Give your application a descriptive name, and select **Integrate any other application you don't find in the gallery (Non-gallery)** option, then click **Create**.
+
+
+
+## Create provision
+
+Go to the application detail page. Select **Provision User Accounts**.
+
+
+
+Click **Get Started** button.
+
+
+
+Change **Provisioning Mode** to **Automatic**.
+
+
+
+Go to your Bytebase console, navigate to **Security & Policy** -> **Users & Groups** page. Click **Sync From Entra ID (Azure AD)**.
+
+
+
+Copy the **Endpoint** and **Secret Token**.
+
+
+
+Bytebase endpoint implements SCIM protocol, please make sure you have configured [External URL](/get-started/self-host/external-url) and it's network accessible from Entra.
+
+
+
+
+
+Go back to Entra console, paste the `Endpoint` and `Secret Token` above to `Tenant URL` and `Secret Token` respectively.
+Click **Test Connection** and save upon success.
+
+
+
+## Edit attribute mapping
+
+Continue the provision, click **Mappings** and click **Provision Microsoft Entra ID Groups**.
+
+
+
+Bytebase uses the group's `externalId` to uniquely identify a group. By default, Entra ID maps `objectId` to `externalId`, which is stable and recommended. You can optionally add a custom `email` attribute to sync the group email to Bytebase.
+
+
+
+If you have an existing SCIM configuration that maps `externalId` to `mail`, it will continue to work. However, we recommend switching to the default `objectId` mapping for stability, since object IDs do not change when a group's email is updated.
+
+
+
+### Step 1 - Create a new `email` attribute
+
+Click **Show advanced options**, then click **Edit attribute list for Bytebase**.
+
+
+
+Add a new attribute `email` with type `String`, then click **Save**.
+
+
+
+### Step 2 - Edit the mapping
+
+Edit the attribute mapping:
+
+- Click **Edit** for the `displayName` row. Change **Match objects using this attribute** to `No`.
+- Click **Edit** for the `externalId` row. Change **Match objects using this attribute** to `Yes` and set **Matching precedence** to `1`.
+- Add a new mapping row: set **email** to map to **mail**.
+
+
+
+The final mappings look like this.
+
+
+
+## Assign users and groups
+
+In order for your users and groups to be synced to Bytebase, you will need to assign them to your Entra SCIM application. Select **Users and groups** and click **Add user/group**.
+
+
+
+Click **None selected** under the **Users and Groups**. Select the users and groups that you want to add to the SCIM application, and click **Select** and **Assign**.
+
+
+
+## Turn on provisioning
+
+On the application overview page, click **Start provisioning**. To test syncing, we recommend starting with **Provision on demand** for a subset of users or groups.
+
+
+
+Afterwards, Entra will sync the users and groups to Bytebase periodically.
diff --git a/docs/administration/scim/okta.mdx b/docs/administration/scim/okta.mdx
new file mode 100644
index 00000000..fa1e9579
--- /dev/null
+++ b/docs/administration/scim/okta.mdx
@@ -0,0 +1,119 @@
+---
+title: Okta
+---
+
+## Get SCIM credentials from Bytebase
+
+1. Log in to Bytebase as a **Workspace Admin**.
+2. Navigate to **Settings** -> **General** -> **Network**.
+3. Ensure **External URL** is configured (e.g., `https://bytebase.example.com`).
+4. Navigate to **Settings** -> **Members**.
+5. Click the **Directory Sync** button (or gear icon).
+6. In the Directory Sync drawer, you'll find:
+ - **SCIM Endpoint URL**: `https:///hook/scim/workspaces/`
+ - **Secret Token**: Bearer token for authentication
+7. Copy both values - you'll need them in the next steps.
+
+
+
+## Create SCIM application in Okta
+
+1. Log in to the **Okta Admin Console** (`https://your-domain-admin.okta.com`).
+2. In the left navigation, go to **Applications** -> **Applications**.
+3. Click **Create App Integration**.
+4. Select **SWA - Secure Web Authentication** and click **Next**.
+
+
+
+5. Configure the application:
+ - **App name**: `Bytebase SCIM`
+ - **App login page URL**: Your Bytebase external URL
+ - You can also check "Do not display application icon to users" and "This is an internal application that we created" since it's only used for data sync.
+
+
+
+## Configure API integration
+
+1. Go to the **General** tab, in the **App Settings** section, click **Edit**.
+
+
+
+2. Find the **Provisioning** field and select **SCIM**, then save the setting. After saving, the **Provisioning** tab will appear in the application.
+
+
+
+3. Go to the **Provisioning** tab, edit the integration:
+ - **SCIM connector base URL**: The SCIM Endpoint URL from Bytebase (e.g., `https://bytebase.example.com/hook/scim/workspaces/abc123`)
+ - **Unique identifier field for users**: `userName`
+ - **Authentication Mode**: HTTP Header
+ - **Authorization**: The Secret Token from Bytebase
+
+
+
+4. Click **Test Connector Configuration** and save upon success.
+
+## Enable provisioning features
+
+1. Still on the **Provisioning** tab, click **To App** in the left sidebar.
+2. Click **Edit** in the Provisioning to App section.
+3. Enable the following features:
+ - **Create Users**
+ - **Update User Attributes**
+ - **Deactivate Users**
+4. Click **Save**.
+
+
+
+## Configure user attribute mappings
+
+No changes are needed for the default attribute mapping configuration.
+
+## Assign users to the application
+
+### Assign individual users
+
+1. Go to the **Assignments** tab.
+2. Click **Assign** -> **Assign to People**.
+3. Find and select the users you want to provision.
+4. Click **Assign** next to each user.
+5. Review the user's attribute values (you can customize per user if needed).
+6. Click **Save and Go Back**.
+7. Click **Done** when finished.
+
+### Assign groups (preferred)
+
+1. Go to the **Assignments** tab.
+2. Click **Assign** -> **Assign to Groups**.
+3. Select the groups whose members should be provisioned.
+
+
+
+4. Click **Assign**, review the attribute values, and click **Save and Go Back**.
+
+
+
+
+
+5. Click **Done** when finished.
+
+
+
+Assigning a group provisions all members as users, but **does not create the group in Bytebase**. To sync groups, see [Configure group push](#configure-group-push) below.
+
+
+
+## Configure group push
+
+To sync Okta groups to Bytebase (not just group members as users):
+
+1. Go to the **Push Groups** tab.
+2. Click **Push Groups**, search group by name or rule.
+3. Click **Save**, then wait and check the status.
+
+
+
+After the status changes to **Active**, the groups are successfully synced to Bytebase.
+
+
+
+
diff --git a/docs/administration/scim/overview.mdx b/docs/administration/scim/overview.mdx
index 0a58ae79..fcbfffbe 100644
--- a/docs/administration/scim/overview.mdx
+++ b/docs/administration/scim/overview.mdx
@@ -1,10 +1,13 @@
---
-title: SCIM
+title: Overview
---
SCIM (System for Cross-domain Identity Management) is a standard for provisioning and deprovisioning users and groups in an organization.
-Bytebase implements SCIM 2.0 and provides built-in support for Entra ID (Azure AD) and Okta.
+Bytebase implements SCIM 2.0 and provides built-in support for the following identity providers:
+
+- [Entra ID (Azure AD)](/administration/scim/entra-id)
+- [Okta](/administration/scim/okta)
| IdP | User | Group | Role | Interval |
| ------------------- | ------------------- | ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -15,106 +18,3 @@ Bytebase implements SCIM 2.0 and provides built-in support for Entra ID (Azure A
- You must be the **Workspace Admin** to configure SCIM.
- Configure [External URL](/get-started/self-host/external-url).
-
-## Entra ID
-
-
-
-### Create enterprise application
-
-Sign in to the Entra ID Admin Center Dashboard. Select **Enterprise applications** and click **New application**.
-
-
-
-Select **Create your own application**. Give your application a descriptive name, and select **Integrate any other application you don’t find in the gallery (Non-gallery)** option, then click **Create**.
-
-
-
-### Create provision
-
-Go to the application detail page. Select **Provision User Accounts**.
-
-
-
-Click **Get Started** button.
-
-
-
-Change **Provisioning Mode** to **Automatic**.
-
-
-
-Go to your Bytebase console, navigate to **Security & Policy** -> **Users & Groups** page. Click **Sync From Entra ID (Azure AD)**.
-
-
-
-Copy the **Endpoint** and **Secret Token**.
-
-
-
-Bytebase endpoint implements SCIM protocol, please make sure you have configured [External URL](/get-started/self-host/external-url) and it's network accessible from Entra.
-
-
-
-
-
-Go back to Entra console, paste the `Endpoint` and `Secret Token` above to `Tenant URL` and `Secret Token` respectively.
-Click **Test Connection** and save upon success.
-
-
-
-### Edit attribute mapping
-
-Continue the provision, click **Mappings** and click **Provision Microsoft Entra ID Groups**.
-
-
-
-Bytebase uses the group's `externalId` to uniquely identify a group. By default, Entra ID maps `objectId` to `externalId`, which is stable and recommended. You can optionally add a custom `email` attribute to sync the group email to Bytebase.
-
-
-
-If you have an existing SCIM configuration that maps `externalId` to `mail`, it will continue to work. However, we recommend switching to the default `objectId` mapping for stability, since object IDs do not change when a group's email is updated.
-
-
-
-#### Step 1 - Create a new `email` attribute
-
-Click **Show advanced options**, then click **Edit attribute list for Bytebase**.
-
-
-
-Add a new attribute `email` with type `String`, then click **Save**.
-
-
-
-#### Step 2 - Edit the mapping
-
-Edit the attribute mapping:
-
-- Click **Edit** for the `displayName` row. Change **Match objects using this attribute** to `No`.
-- Click **Edit** for the `externalId` row. Change **Match objects using this attribute** to `Yes` and set **Matching precedence** to `1`.
-- Add a new mapping row: set **email** to map to **mail**.
-
-
-
-The final mappings look like this.
-
-
-
-### Assign users and groups
-
-In order for your users and groups to be synced to Bytebase, you will need to assign them to your Entra SCIM application. Select **Users and groups** and click **Add user/group**.
-
-
-
-Click **None selected** under the **Users and Groups**. Select the users and groups that you want to add to the SCIM application, and click **Select** and **Assign**.
-
-
-
-### Turn on provisioning
-
-On the application overview page, click **Start provisioning**. To test syncing, we recommend starting with **Provision on demand** for a subset of users or groups.
-
-
-
-Afterwards, Entra will sync the users and groups to Bytebase periodically.
diff --git a/docs/content/docs/administration/scim/okta/assign-groups-attributes.webp b/docs/content/docs/administration/scim/okta/assign-groups-attributes.webp
new file mode 100644
index 00000000..699bc17a
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/assign-groups-attributes.webp differ
diff --git a/docs/content/docs/administration/scim/okta/assign-groups-dialog.webp b/docs/content/docs/administration/scim/okta/assign-groups-dialog.webp
new file mode 100644
index 00000000..7abc5d50
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/assign-groups-dialog.webp differ
diff --git a/docs/content/docs/administration/scim/okta/assign-to-groups.webp b/docs/content/docs/administration/scim/okta/assign-to-groups.webp
new file mode 100644
index 00000000..f95e5626
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/assign-to-groups.webp differ
diff --git a/docs/content/docs/administration/scim/okta/bytebase-groups-synced.webp b/docs/content/docs/administration/scim/okta/bytebase-groups-synced.webp
new file mode 100644
index 00000000..e8ace204
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/bytebase-groups-synced.webp differ
diff --git a/docs/content/docs/administration/scim/okta/bytebase-setting.webp b/docs/content/docs/administration/scim/okta/bytebase-setting.webp
new file mode 100644
index 00000000..c8aa1488
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/bytebase-setting.webp differ
diff --git a/docs/content/docs/administration/scim/okta/create-app-integration.webp b/docs/content/docs/administration/scim/okta/create-app-integration.webp
new file mode 100644
index 00000000..04503b51
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/create-app-integration.webp differ
diff --git a/docs/content/docs/administration/scim/okta/create-swa-integration.webp b/docs/content/docs/administration/scim/okta/create-swa-integration.webp
new file mode 100644
index 00000000..6132a85f
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/create-swa-integration.webp differ
diff --git a/docs/content/docs/administration/scim/okta/general-tab-edit.webp b/docs/content/docs/administration/scim/okta/general-tab-edit.webp
new file mode 100644
index 00000000..8e98b654
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/general-tab-edit.webp differ
diff --git a/docs/content/docs/administration/scim/okta/provisioning-scim.webp b/docs/content/docs/administration/scim/okta/provisioning-scim.webp
new file mode 100644
index 00000000..1fed57ad
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/provisioning-scim.webp differ
diff --git a/docs/content/docs/administration/scim/okta/provisioning-to-app.webp b/docs/content/docs/administration/scim/okta/provisioning-to-app.webp
new file mode 100644
index 00000000..867079fc
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/provisioning-to-app.webp differ
diff --git a/docs/content/docs/administration/scim/okta/push-groups-active.webp b/docs/content/docs/administration/scim/okta/push-groups-active.webp
new file mode 100644
index 00000000..e48bb4cd
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/push-groups-active.webp differ
diff --git a/docs/content/docs/administration/scim/okta/push-groups.webp b/docs/content/docs/administration/scim/okta/push-groups.webp
new file mode 100644
index 00000000..36310a1e
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/push-groups.webp differ
diff --git a/docs/content/docs/administration/scim/okta/scim-connection.webp b/docs/content/docs/administration/scim/okta/scim-connection.webp
new file mode 100644
index 00000000..fdfa6182
Binary files /dev/null and b/docs/content/docs/administration/scim/okta/scim-connection.webp differ
diff --git a/docs/docs.json b/docs/docs.json
index 9c1364ad..74aaabe0 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -251,7 +251,14 @@
]
},
"administration/roles",
- "administration/scim/overview",
+ {
+ "group": "SCIM",
+ "pages": [
+ "administration/scim/overview",
+ "administration/scim/entra-id",
+ "administration/scim/okta"
+ ]
+ },
"administration/2fa",
"administration/password",
"administration/sign-in-restriction"