chore: update docs for okta sync #1006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

d-bytebase merged 1 commit into main from chore/okta

Feb 3, 2026

docs/administration/scim/entra-id.mdx

-Original file line number
+Diff line change
@@ -0,0 +1,104 @@
+    ---
+    title: Entra ID
+    ---
+    <Card title="Tutorial: Managing user account provisioning for enterprise apps in Entra" icon="graduation-cap" href="https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal" horizontal />
+    ## Create enterprise application
+    Sign in to the Entra ID Admin Center Dashboard. Select **Enterprise applications** and click **New application**.
+    ![create-application](/content/docs/administration/scim/entra/create-application.webp)
+    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-own-application](/content/docs/administration/scim/entra/create-own-application.webp)
+    ## Create provision
+    Go to the application detail page. Select **Provision User Accounts**.
+    ![provision-user-accounts](/content/docs/administration/scim/entra/provision-user-accounts.webp)
+    Click **Get Started** button.
+    ![provision-get-started](/content/docs/administration/scim/entra/provision-get-started.webp)
+    Change **Provisioning Mode** to **Automatic**.
+    ![provision-automatic](/content/docs/administration/scim/entra/provision-automatic.webp)
+    Go to your Bytebase console, navigate to **Security & Policy** -> **Users & Groups** page. Click **Sync From Entra ID (Azure AD)**.
+    ![bytebase-sync-from-entra](/content/docs/administration/scim/entra/bytebase-sync-from-entra.webp)
+    Copy the **Endpoint** and **Secret Token**.
+    <Note>
+    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.
+    </Note>
+    ![bytebase-setting](/content/docs/administration/scim/entra/bytebase-setting.webp)
+    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.
+    ![provision-admin-credentials](/content/docs/administration/scim/entra/provision-admin-credentials.webp)
+    ## Edit attribute mapping
+    Continue the provision, click **Mappings** and click **Provision Microsoft Entra ID Groups**.
+    ![provision-group](/content/docs/administration/scim/entra/provision-group.webp)
+    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.
+    <Note>
+    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.
+    </Note>
+    ### Step 1 - Create a new `email` attribute
+    Click **Show advanced options**, then click **Edit attribute list for Bytebase**.
+    ![mapping-create-email-attr](/content/docs/administration/scim/entra/mapping-create-email-attr.webp)
+    Add a new attribute `email` with type `String`, then click **Save**.
+    ![mapping-email-attr-config](/content/docs/administration/scim/entra/mapping-email-attr-config.webp)
+    ### 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**.
+    ![mapping-edit-mapping](/content/docs/administration/scim/entra/mapping-edit-mapping.webp)
+    The final mappings look like this.
+    ![mapping-final](/content/docs/administration/scim/entra/mapping-final.webp)
+    ## 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**.
+    ![add-user-group](/content/docs/administration/scim/entra/add-user-group.webp)
+    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**.
+    ![assign-user-group](/content/docs/administration/scim/entra/assign-user-group.webp)
+    ## 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.
+    ![start-provision](/content/docs/administration/scim/entra/start-provision.webp)
+    Afterwards, Entra will sync the users and groups to Bytebase periodically.

docs/administration/scim/okta.mdx

-Original file line number
+Diff line change
@@ -0,0 +1,119 @@
+    ---
+    title: Okta
+    ---
+    ## Get SCIM credentials from Bytebase
+. Log in to Bytebase as a **Workspace Admin**.
+. Navigate to **Settings** -> **General** -> **Network**.
+. Ensure **External URL** is configured (e.g., `https://bytebase.example.com`).
+. Navigate to **Settings** -> **Members**.
+. Click the **Directory Sync** button (or gear icon).
+. In the Directory Sync drawer, you'll find:
+       - **SCIM Endpoint URL**: `https://<your-bytebase-url>/hook/scim/workspaces/<workspace-id>`
+       - **Secret Token**: Bearer token for authentication
+. Copy both values - you'll need them in the next steps.
+    ![bytebase-setting](/content/docs/administration/scim/okta/bytebase-setting.webp)
+    ## Create SCIM application in Okta
+. Log in to the **Okta Admin Console** (`https://your-domain-admin.okta.com`).
+. In the left navigation, go to **Applications** -> **Applications**.
+. Click **Create App Integration**.
+. Select **SWA - Secure Web Authentication** and click **Next**.
+    ![create-app-integration](/content/docs/administration/scim/okta/create-app-integration.webp)
+. 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.
+    ![create-swa-integration](/content/docs/administration/scim/okta/create-swa-integration.webp)
+    ## Configure API integration
+. Go to the **General** tab, in the **App Settings** section, click **Edit**.
+    ![general-tab-edit](/content/docs/administration/scim/okta/general-tab-edit.webp)
+. Find the **Provisioning** field and select **SCIM**, then save the setting. After saving, the **Provisioning** tab will appear in the application.
+    ![provisioning-scim](/content/docs/administration/scim/okta/provisioning-scim.webp)
+. 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
+    ![scim-connection](/content/docs/administration/scim/okta/scim-connection.webp)
+. Click **Test Connector Configuration** and save upon success.
+    ## Enable provisioning features
+. Still on the **Provisioning** tab, click **To App** in the left sidebar.
+. Click **Edit** in the Provisioning to App section.
+. Enable the following features:
+       - **Create Users**
+       - **Update User Attributes**
+       - **Deactivate Users**
+. Click **Save**.
+    ![provisioning-to-app](/content/docs/administration/scim/okta/provisioning-to-app.webp)
+    ## Configure user attribute mappings
+    No changes are needed for the default attribute mapping configuration.
+    ## Assign users to the application
+    ### Assign individual users
+. Go to the **Assignments** tab.
+. Click **Assign** -> **Assign to People**.
+. Find and select the users you want to provision.
+. Click **Assign** next to each user.
+. Review the user's attribute values (you can customize per user if needed).
+. Click **Save and Go Back**.
+. Click **Done** when finished.
+    ### Assign groups (preferred)
+. Go to the **Assignments** tab.
+. Click **Assign** -> **Assign to Groups**.
+. Select the groups whose members should be provisioned.
+    ![assign-to-groups](/content/docs/administration/scim/okta/assign-to-groups.webp)
+. Click **Assign**, review the attribute values, and click **Save and Go Back**.
+    ![assign-groups-dialog](/content/docs/administration/scim/okta/assign-groups-dialog.webp)
+    ![assign-groups-attributes](/content/docs/administration/scim/okta/assign-groups-attributes.webp)
+. Click **Done** when finished.
+    <Note>
+    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.
+    </Note>
+    ## Configure group push
+    To sync Okta groups to Bytebase (not just group members as users):
+. Go to the **Push Groups** tab.
+. Click **Push Groups**, search group by name or rule.
+. Click **Save**, then wait and check the status.
+    ![push-groups](/content/docs/administration/scim/okta/push-groups.webp)
+    After the status changes to **Active**, the groups are successfully synced to Bytebase.
+    ![push-groups-active](/content/docs/administration/scim/okta/push-groups-active.webp)
+    ![bytebase-groups-synced](/content/docs/administration/scim/okta/bytebase-groups-synced.webp)

docs/administration/scim/overview.mdx

-Original file line number
+Diff line change
@@ -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                                                                                                                                                                                      |
     | ------------------- | ------------------- | ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ Expand All @@
     - You must be the **Workspace Admin** to configure SCIM.
     - Configure [External URL](/get-started/self-host/external-url).
-    ## Entra ID
-    <Card title="Tutorial: Managing user account provisioning for enterprise apps in Entra" icon="graduation-cap" href="https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal" horizontal />
-    ### Create enterprise application
-    Sign in to the Entra ID Admin Center Dashboard. Select **Enterprise applications** and click **New application**.
-    ![create-application](/content/docs/administration/scim/entra/create-application.webp)
-    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-own-application](/content/docs/administration/scim/entra/create-own-application.webp)
-    ### Create provision
-    Go to the application detail page. Select **Provision User Accounts**.
-    ![provision-user-accounts](/content/docs/administration/scim/entra/provision-user-accounts.webp)
-    Click **Get Started** button.
-    ![provision-get-started](/content/docs/administration/scim/entra/provision-get-started.webp)
-    Change **Provisioning Mode** to **Automatic**.
-    ![provision-automatic](/content/docs/administration/scim/entra/provision-automatic.webp)
-    Go to your Bytebase console, navigate to **Security & Policy** -> **Users & Groups** page. Click **Sync From Entra ID (Azure AD)**.
-    ![bytebase-sync-from-entra](/content/docs/administration/scim/entra/bytebase-sync-from-entra.webp)
-    Copy the **Endpoint** and **Secret Token**.
-    <Note>
-    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.
-    </Note>
-    ![bytebase-setting](/content/docs/administration/scim/entra/bytebase-setting.webp)
-    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.
-    ![provision-admin-credentials](/content/docs/administration/scim/entra/provision-admin-credentials.webp)
-    ### Edit attribute mapping
-    Continue the provision, click **Mappings** and click **Provision Microsoft Entra ID Groups**.
-    ![provision-group](/content/docs/administration/scim/entra/provision-group.webp)
-    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.
-    <Note>
-    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.
-    </Note>
-    #### Step 1 - Create a new `email` attribute
-    Click **Show advanced options**, then click **Edit attribute list for Bytebase**.
-    ![mapping-create-email-attr](/content/docs/administration/scim/entra/mapping-create-email-attr.webp)
-    Add a new attribute `email` with type `String`, then click **Save**.
-    ![mapping-email-attr-config](/content/docs/administration/scim/entra/mapping-email-attr-config.webp)
-    #### 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**.
-    ![mapping-edit-mapping](/content/docs/administration/scim/entra/mapping-edit-mapping.webp)
-    The final mappings look like this.
-    ![mapping-final](/content/docs/administration/scim/entra/mapping-final.webp)
-    ### 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**.
-    ![add-user-group](/content/docs/administration/scim/entra/add-user-group.webp)
-    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**.
-    ![assign-user-group](/content/docs/administration/scim/entra/assign-user-group.webp)
-    ### 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.
-    ![start-provision](/content/docs/administration/scim/entra/start-provision.webp)
-    Afterwards, Entra will sync the users and groups to Bytebase periodically.

docs/content/docs/administration/scim/okta/assign-groups-attributes.webp

Sorry, something went wrong. Reload?