diff --git a/mintlify/administration/sso/oidc-entra-id.mdx b/mintlify/administration/sso/oidc-entra-id.mdx new file mode 100644 index 000000000..c90a5e304 --- /dev/null +++ b/mintlify/administration/sso/oidc-entra-id.mdx @@ -0,0 +1,164 @@ +--- +title: Microsoft Entra ID (Azure AD) OIDC +feature_name: SSO_ADVANCED +--- + +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. + + + +Please make sure the [`--external-url`](/get-started/self-host/external-url) is configured correctly for the Bytebase workspace. + +If you start Bytebase with `--external-url http://bytebase.example.com`, then your application redirect URL should be `http://bytebase.example.com/oidc/callback`. + + + +## Step 1: Create App Registration + +1. Navigate to [Azure Portal](https://portal.azure.com) +2. Go to **Microsoft Entra ID** (formerly **Azure Active Directory**) → **App registrations** +3. Click **New registration** +4. Configure the application: + - **Name**: `Bytebase SSO` (or your preferred name) + - **Supported account types**: Choose based on your requirements (single or multi-tenant) + - **Redirect URI**: + - Platform: `Web` + - URI: `https://your-bytebase-domain.com/oidc/callback` +5. Click **Register** + +## Step 2: Configure Authentication + +1. In your app registration, go to **Authentication** +2. Verify your redirect URI under **Platform configurations** +3. Under **Implicit grant and hybrid flows**: + - Check **ID tokens** (used for implicit and hybrid flows) +4. Click **Save** + +## Step 3: Configure API Permissions + +1. Go to **API permissions** +2. Click **Add a permission** → **Microsoft Graph** → **Delegated permissions** +3. Add the following permissions: + + - `openid` (Sign users in) + - `profile` (View users' basic profile) + - `email` (View users' email address) + - `offline_access` (Maintain access to data) + - `User.Read` (Sign in and read user profile) + - `GroupMember.Read.All` (Read group memberships) - **Required for group syncing** + +4. Click **Add permissions** +5. If required by your organization, click **Grant admin consent** + +## Step 4: Configure Group Claims + +For group synchronization to work, configure group claims: + +1. Go to **Token configuration** +2. Click **Add groups claim** +3. Configure the groups claim: + + - **Select group types**: Choose **Security groups** + - **Customize token properties**: + - For **ID**: Select `Group ID` (returns GUIDs) or `Cloud-only group display names` (returns readable names) + - For better control, select **Groups assigned to the application** + +4. Click **Add** + +## Step 5: Create Client Secret + +1. Go to **Certificates & secrets** +2. Click **New client secret** +3. Add description: `Bytebase OIDC` +4. Select expiration period (recommend 24 months) +5. Click **Add** +6. **Important**: Copy the secret value immediately (it won't be shown again) + +## Step 6: Gather Configuration Information + +From the **Overview** page, collect: + +- **Application (client) ID**: Your client ID +- **Directory (tenant) ID**: Your tenant ID + +Construct the issuer URL: + +```text +https://login.microsoftonline.com/{tenant-id}/v2.0 +``` + +## Step 7: Configure Bytebase OIDC + +1. Log into Bytebase as an admin +2. Navigate to **Settings** → **SSO** → **Create** +3. Select **OIDC** as the provider type +4. Configure with the following settings: + +**Basic Information:** + +- **Name**: `Entra ID` +- **Identity Provider ID**: `entra-id` +- **Domain**: Your organization domain (optional) + +**Identity Provider Information:** + +- **Issuer**: `https://login.microsoftonline.com/{your-tenant-id}/v2.0` +- **Client ID**: Your application client ID +- **Client Secret**: Your client secret +- **Scopes**: `openid profile email offline_access` + +**User Information Field Mapping:** + +- **Email**: `email` +- **Display Name**: `name` +- **Groups**: `groups` (Important for group syncing) + +5. Click **Create** + +## Step 8: Test the Configuration + +1. Click **Test Connection** in Bytebase +2. You should be redirected to Microsoft login +3. After successful authentication, verify: + - User information is correctly mapped + - Groups are being returned (if configured) + +## Group Synchronization + +If you configured group claims, Bytebase will automatically sync user groups: + +1. Go to **Settings** → **Groups** in Bytebase +2. Create groups that match your Entra ID groups: + - If using Group IDs, create groups with GUID names + - If using display names, create groups with matching names +3. Assign appropriate roles to these groups + +Users will be automatically added to matching Bytebase groups upon login. + +## Example Group Synchronization Flow + +1. User logs in via Entra ID +2. ID token includes groups claim: `["c80adaad-11c0-4ad9-aa31-7ef37029aa2a", "6525b949-f790-4807-bf85-707fa6ec4cb4"]` +3. Bytebase receives and processes groups +4. User is automatically added to matching Bytebase groups +5. User receives permissions based on group membership + +## Troubleshooting + +### Groups Not Appearing + +1. **Check Token Configuration**: Ensure groups claim is added for ID tokens +2. **Verify Permissions**: Ensure `GroupMember.Read.All` permission is granted +3. **Check Group Types**: Verify users are members of security groups +4. **Enable Debug Logging**: Run Bytebase with `--debug` flag to see claim details + +### Common Issues + +1. **Groups showing as GUIDs**: This is normal when using Group ID format +2. **Missing groups**: Ensure groups are assigned to the application if using that filter +3. **Token size limitations**: Consider using "Groups assigned to the application" for users with many groups + +## Reference + +- [Microsoft identity platform and OpenID Connect protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) +- [Configure group claims for applications](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims) diff --git a/mintlify/administration/sso/overview.mdx b/mintlify/administration/sso/overview.mdx index 9beea30e6..3dd213a4f 100644 --- a/mintlify/administration/sso/overview.mdx +++ b/mintlify/administration/sso/overview.mdx @@ -8,6 +8,7 @@ Bytebase supports the following standard protocols that provide SSO: - [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) ## Prerequisites diff --git a/mintlify/docs.json b/mintlify/docs.json index 26dbac0a4..ca4192e12 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -195,6 +195,7 @@ "administration/sso/overview", "administration/sso/oauth2", "administration/sso/oidc", + "administration/sso/oidc-entra-id", "administration/sso/ldap" ] },