docs: update & reorganize about users & sso & scim

docs/administration/service-account.mdx

@@ -0,0 +1,33 @@
+---
+title: Service Account
+---
+
+Service accounts are machine identities designed for automated processes and applications. Unlike human [users](/administration/user-groups/overview), service accounts authenticate via API keys and are intended for programmatic access.
+
+## Workspace vs Project Level
+
+Service accounts can be created at two levels:
+
+- **Workspace level** — Has access governed by workspace IAM policies. Suitable for cross-project automation.
+- **Project level** — Scoped to a single project, following the principle of least privilege. Suitable for isolated automation within one project.
+
+## Create a Service Account
+
+1. For workspace-level: go to **IAM & Admin** > **Service Accounts** tab and click **Add Service Account**.
+2. For project-level: go to **Project** > **Manage** > **Service Accounts** and click **Add Service Account**.
+
+<Note>
+
+Service accounts cannot be part of [user groups](/administration/user-groups/overview). Since service accounts are for automated processes with specific access needs, including them in groups could grant unintended permissions. This is considered an [anti-pattern](https://cloud.google.com/iam/docs/best-practices-service-accounts#groups).
+
+</Note>
+
+## Service Account vs Workload Identity
+
+| | Service Account | [Workload Identity](/administration/workload-identity/overview) |
+|---|---|---|
+| **Credential** | Long-lived API key | Short-lived OIDC token |
+| **Best for** | Scripts, Terraform, general API access | CI/CD pipelines (GitHub Actions, GitLab CI) |
+| **Security** | Key must be stored as a secret | No secrets to manage |
+
+If your automation runs in a CI/CD platform that supports OIDC, prefer [Workload Identity](/administration/workload-identity/overview) for better security.

docs/administration/sso/idp-initiated.mdx

@@ -2,32 +2,7 @@
 title: IdP-Initiated Flow
 ---
 
-Identity Provider-initiated (IdP-initiated) flow allows users to access Bytebase directly from their identity provider's dashboard or portal, without needing to first visit Bytebase and click a "Sign in with..." button.
-
-## Overview
-
-In a traditional Service Provider-initiated (SP-initiated) flow, the authentication process starts when a user tries to access Bytebase and clicks the SSO login button. With IdP-initiated flow, the process begins at the identity provider's side—for example, when a user clicks the Bytebase tile in their Okta dashboard.
-
-### IdP-Initiated vs SP-Initiated
-
-**SP-Initiated (Traditional Flow)**:
-
-1. User visits Bytebase
-2. User clicks "Sign in with Okta" button
-3. User is redirected to Okta for authentication
-4. After authentication, user is redirected back to Bytebase
-
-**IdP-Initiated Flow**:
-
-1. User is already logged into their IdP (e.g., Okta)
-2. User clicks Bytebase tile/bookmark in their IdP dashboard
-3. User is directly authenticated and redirected to Bytebase
-
-### Benefits
-
-- **Streamlined user experience**: Users can access Bytebase with a single click from their IdP dashboard
-- **Centralized access**: All applications are accessible from one place (the IdP portal)
-- **Reduced friction**: Eliminates the extra step of clicking the SSO button in Bytebase
+By default, SSO uses a **Service Provider-initiated (SP-initiated)** flow: users visit Bytebase, click "Sign in with X", get redirected to the identity provider, then back. **IdP-initiated** flow reverses this — users click the Bytebase tile directly from their identity provider's dashboard (e.g. Okta portal) and land in Bytebase already authenticated. This eliminates the extra step of visiting Bytebase first and works with both OAuth 2.0 and OIDC providers.
 
 ## Prerequisites
 

docs/administration/sso/oidc-entra-id.mdx

@@ -1,8 +1,14 @@
 ---
-title: Microsoft Entra ID (Azure AD) OIDC
+title: OIDC with Microsoft Entra ID
 ---
 
-Microsoft Entra ID (formerly Azure Active Directory) can be configured as an OpenID Connect (OIDC) identity provider for Bytebase, providing secure Single Sign-On with group synchronization support.
+This guide walks through configuring Microsoft Entra ID (formerly Azure Active Directory) as an [OIDC](/administration/sso/oidc) identity provider for Bytebase, including group synchronization.
+
+<Note>
+
+Entra ID can also be configured via [OAuth 2.0](/administration/sso/oauth2#microsoft-entra-azure-ad) if you don't need group syncing or OIDC-specific features.
+
+</Note>
 
 <Info>
 

docs/administration/sso/oidc.mdx

@@ -4,6 +4,12 @@ title: OpenID Connect (OIDC)
 
 OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. Bytebase supports using OIDC for configuring Single Sign-On (SSO).
 
+<Tip>
+
+For **Microsoft Entra ID (Azure AD)**, see the dedicated [Entra ID OIDC guide](/administration/sso/oidc-entra-id) which covers app registration, API permissions, group claims, and troubleshooting.
+
+</Tip>
+
 ## Configuration
 
 <Info>

docs/administration/sso/overview.mdx

@@ -4,13 +4,44 @@ title: Overview
 
 Single Sign-On (SSO) is an authentication method that enables users to securely authenticate with multiple applications and websites by using just one set of credentials.
 
-Bytebase supports the following standard protocols that provide SSO:
+## Supported Protocols
 
-- [OAuth 2.0](/administration/sso/oauth2)
-- [OpenID Connect (OIDC)](/administration/sso/oidc)
-- [Microsoft Entra ID (Azure AD) OIDC](/administration/sso/oidc-entra-id)
-- [Lightweight Directory Access Protocol (LDAP)](/administration/sso/ldap)
-- [IdP-Initiated Flow](/administration/sso/idp-initiated) - Access Bytebase directly from your identity provider's dashboard
+Bytebase supports three SSO protocols:
+
+- **[OAuth 2.0](/administration/sso/oauth2)** — Authorization protocol. Bytebase gets a token and fetches your profile from the provider. Good for providers that don't support OIDC (e.g. GitHub).
+- **[OpenID Connect (OIDC)](/administration/sso/oidc)** — Identity layer built on top of OAuth 2.0. Adds a standardized ID token so Bytebase gets user info directly. Preferred when available.
+- **[LDAP](/administration/sso/ldap)** — Directory lookup protocol. Bytebase queries a user directory directly with username/password. No browser redirects involved.
+
+## Authentication Flow
+
+There are two ways SSO authentication can start:
+
+- **SP-Initiated (default)** — User visits Bytebase, clicks "Sign in with X", gets redirected to the identity provider, then back to Bytebase after authentication.
+- **[IdP-Initiated](/administration/sso/idp-initiated)** — User clicks the Bytebase tile directly from their identity provider's dashboard (e.g. Okta portal) and lands in Bytebase already authenticated. Works with OAuth 2.0 and OIDC providers.
+
+## User & Group Provisioning (SCIM)
+
+SSO handles **authentication** (who is this person), but not **provisioning** (creating/updating/deactivating accounts). For automatic user and group provisioning, Bytebase supports [SCIM 2.0](/administration/scim/overview) with [Entra ID](/administration/scim/entra-id) and [Okta](/administration/scim/okta).
+
+<Warning>
+
+SCIM requires the IdP to communicate with Bytebase over HTTP. **LDAP does not support SCIM** — if you need SCIM with a provider like Microsoft Entra ID, you must configure SSO via [OIDC](/administration/sso/oidc-entra-id) or [OAuth 2.0](/administration/sso/oauth2#microsoft-entra-azure-ad), not LDAP.
+
+</Warning>
+
+## Which Protocol to Use
+
+| Identity Provider | Recommended Protocol | [SCIM](/administration/scim/overview) | Notes |
+|---|---|---|---|
+| Google | [OIDC](/administration/sso/oidc#google) | — | Also available via [OAuth 2.0](/administration/sso/oauth2#google) |
+| GitHub | [OAuth 2.0](/administration/sso/oauth2#github) | — | GitHub does not support OIDC |
+| GitLab | [OIDC](/administration/sso/oidc#gitlab) | — | Also available via [OAuth 2.0](/administration/sso/oauth2#gitlab) |
+| Microsoft Entra ID (Azure AD) | [OIDC](/administration/sso/oidc-entra-id) | [Yes](/administration/scim/entra-id) | Also available via [OAuth 2.0](/administration/sso/oauth2#microsoft-entra-azure-ad) |
+| Okta | [OIDC](/administration/sso/oidc#okta) | [Yes](/administration/scim/okta) | Also available via [LDAP](/administration/sso/ldap#okta) (no SCIM) |
+| Keycloak | [OIDC](/administration/sso/oidc#keycloak) | — | |
+| Casdoor | [OIDC](/administration/sso/oidc#casdoor) | — | |
+| Authing | [OIDC](/administration/sso/oidc#authing) | — | |
+| JumpCloud | [LDAP](/administration/sso/ldap#jumpcloud) | — | |
 
 ## Prerequisites
 

docs/administration/user-groups/overview.mdx

@@ -1,39 +1,23 @@
 ---
-title: Overview
+title: Users & Groups
 ---
 
 ## User
 
-A `User` represents anyone who can access and perform operations in Bytebase. Users include both human team members and service accounts.
+A `User` represents a human team member who can access and perform operations in Bytebase.
 
-## Service Account
-
-Service accounts are special users designed for automated processes and applications.
-
-## Workload Identity
-
-Workload Identity is a secure authentication method for CI/CD pipelines and external services using OpenID Connect (OIDC) tokens, eliminating the need for long-lived credentials.
-
-Unlike traditional Service Accounts that require storing API keys as secrets, Workload Identity:
-- Uses short-lived tokens generated per job
-- Validates tokens against your CI/CD platform's identity provider  
-- Restricts access to specific repositories, branches, and workflows
-
-### Setup Workload Identity
-
-<CardGroup cols={2}>
-  <Card title="GitHub Actions" icon="github" href="/administration/user-groups/workload-identity/github-actions">
-    Configure OIDC authentication for GitHub Actions workflows
-  </Card>
-</CardGroup>
+For machine identities, see [Service Accounts](/administration/service-account) and [Workload Identity](/administration/workload-identity/overview).
 
 ## User Group
 
 A `User Group` organizes multiple users together for easier permission management. Workspace admins create groups and add users, then assign these groups to roles within projects.
 
 <Note>
-- Bytebase does not support nested groups. A group can only contain users, it can't contain another group.
-- Service accounts cannot be part of user groups. Since service accounts are for automated processes with specific access needs, including them in groups could grant unintended permissions. This is considered an [anti-pattern](https://cloud.google.com/iam/docs/best-practices-service-accounts#groups).
+Bytebase does not support nested groups. A group can only contain users, it can't contain another group.
+</Note>
+
+<Note>
+Machine identities (service accounts and workload identities) cannot be part of user groups. Since they are for automated processes with specific access needs, including them in groups could grant unintended permissions. This is considered an [anti-pattern](https://cloud.google.com/iam/docs/best-practices-service-accounts#groups).
 </Note>
 
 ## Add group

docs/administration/user-groups/workload-identity/github-actions.mdx → docs/administration/workload-identity/github-actions.mdx

@@ -84,7 +84,7 @@ jobs:
             -H "Content-Type: application/json" \
             -d "{\"token\": \"${{ steps.bytebase-token.outputs.token }}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}")
 
-          ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.accessToken')
+          ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
           echo "::add-mask::$ACCESS_TOKEN"
           echo "access_token=$ACCESS_TOKEN" >> $GITHUB_OUTPUT
 
@@ -113,7 +113,7 @@ permissions:
 
 env:
   BYTEBASE_URL: https://bytebase.example.com
-  WORKLOAD_IDENTITY_EMAIL: github-deploy@workload.bytebase.com
+  WORKLOAD_IDENTITY_EMAIL: github-actions-deploy@workload.bytebase.com
   PROJECT: projects/my-project
 
 jobs:

docs/administration/user-groups/workload-identity/gitlab-ci.mdx → docs/administration/workload-identity/gitlab-ci.mdx

@@ -13,8 +13,8 @@ This guide explains how to configure Workload Identity for GitLab CI/CD to authe
 
 | Field | Description | Example |
 |-------|-------------|---------|
-| **Name** | Display name for this identity | `GitLab Deploy` |
-| **Email** | Unique email prefix (automatically appended with `@workload.bytebase.com`) | `gitlab-deploy` |
+| **Name** | Display name for this identity | `GitLab CI Deploy` |
+| **Email** | Unique email prefix (automatically appended with `@workload.bytebase.com`) | `gitlab-ci-deploy` |
 | **Platform** | Select GitLab CI | `GitLab CI` |
 | **Group / Username** | GitLab group or username (required) | `my-group` |
 | **Project** | Project name (leave empty to allow all projects) | `my-project` |
@@ -69,10 +69,10 @@ deploy-database:
         -H "Content-Type: application/json" \
         -d "{\"token\": \"${GITLAB_OIDC_TOKEN}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}")
 
-      ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.accessToken')
+      ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
       if [ "$ACCESS_TOKEN" = "null" ] || [ -z "$ACCESS_TOKEN" ]; then
         echo "Failed to get access token"
-        echo $RESPONSE
+        echo "$RESPONSE"
         exit 1
       fi
 

docs/administration/workload-identity/overview.mdx

@@ -0,0 +1,29 @@
+---
+title: Overview
+---
+
+Workload Identity is a secure authentication method for CI/CD pipelines and external services using OpenID Connect (OIDC) tokens, eliminating the need for long-lived credentials.
+
+Unlike [Service Accounts](/administration/service-account) that require storing API keys as secrets, Workload Identity:
+
+- Uses short-lived tokens generated per job
+- Validates tokens against your CI/CD platform's identity provider
+- Restricts access to specific repositories, branches, and workflows
+
+## Workspace vs Project Level
+
+Workload identities can be created at two levels:
+
+- **Workspace level** — Has access governed by workspace IAM policies. Suitable for cross-project CI/CD workflows.
+- **Project level** — Scoped to a single project, following the principle of least privilege. Suitable for project-specific pipelines.
+
+## Supported Platforms
+
+<CardGroup cols={2}>
+  <Card title="GitHub Actions" icon="github" href="/administration/workload-identity/github-actions">
+    Configure OIDC authentication for GitHub Actions workflows
+  </Card>
+  <Card title="GitLab CI/CD" icon="gitlab" href="/administration/workload-identity/gitlab-ci">
+    Configure OIDC authentication for GitLab CI/CD pipelines
+  </Card>
+</CardGroup>

docs/changelog/bytebase-3-13-0.mdx

@@ -38,7 +38,7 @@ import InstallUpgrade from '/snippets/install/install-upgrade.mdx';
 ## 🚀 Features
 
 - Support [MCP integration](/integrations/mcp).
-- Add **Workload Identity** as a dedicated account type for OIDC-based authentication, with [GitHub Actions support](/administration/user-groups/workload-identity/github-actions).
+- Add **Workload Identity** as a dedicated account type for OIDC-based authentication, with [GitHub Actions support](/administration/workload-identity/github-actions).
 - Support direct messages for **Microsoft Teams**.
 
 ## 🎄 Enhancements

docs/changelog/bytebase-3-14-0.mdx

@@ -77,7 +77,7 @@ import InstallUpgrade from '/snippets/install/install-upgrade.mdx';
 
 - Improve access and refresh token support. Add refresh tokens (previously only access tokens on the web were supported) and allow separate configuration of **access token duration** and **refresh token duration** (previously the sign-in frequency setting).
 - Allow setting `No approval required` in approval rules when configured conditions are met.
-- Support [**Workload Identity** with **GitLab**](/administration/user-groups/workload-identity/gitlab-ci).
+- Support [**Workload Identity** with **GitLab**](/administration/workload-identity/gitlab-ci).
 
 ## 🎄 Enhancements
 

docs/docs.json

@@ -231,6 +231,17 @@
           {
             "group": "Security",
             "pages": [
+              "administration/user-groups/overview",
+              "administration/service-account",
+              {
+                "group": "Workload Identity",
+                "pages": [
+                  "administration/workload-identity/overview",
+                  "administration/workload-identity/github-actions",
+                  "administration/workload-identity/gitlab-ci"
+                ]
+              },
+              "administration/roles",
               {
                 "group": "Single Sign-On",
                 "pages": [
@@ -242,15 +253,6 @@
                   "administration/sso/idp-initiated"
                 ]
               },
-              {
-                "group": "Users & Groups",
-                "pages": [
-                  "administration/user-groups/overview",
-                  "administration/user-groups/workload-identity/github-actions",
-                  "administration/user-groups/workload-identity/gitlab-ci"
-                ]
-              },
-              "administration/roles",
               {
                 "group": "SCIM",
                 "pages": [
@@ -259,8 +261,8 @@
                   "administration/scim/okta"
                 ]
               },
-              "administration/2fa",
               "administration/password",
+              "administration/2fa",
               "administration/sign-in-restriction"
             ]
           },