Skip to content

Commit 48d3ac0

Browse files
boojackclaudeCopilot
authored
docs: add Microsoft Entra ID OIDC SSO configuration guide (#819)
* docs: add Microsoft Entra ID OIDC SSO configuration guide 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * chore: update * Update mintlify/administration/sso/oidc-entra-id.mdx Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 4189030 commit 48d3ac0

File tree

3 files changed

+166
-0
lines changed

3 files changed

+166
-0
lines changed

‎mintlify/administration/sso/oidc-entra-id.mdx‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: Microsoft Entra ID (Azure AD) OIDC
3+
feature_name: SSO_ADVANCED
4+
---
5+
6+
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.
7+
8+
<Info>
9+
10+
Please make sure the [`--external-url`](/get-started/self-host/external-url) is configured correctly for the Bytebase workspace.
11+
12+
If you start Bytebase with `--external-url http://bytebase.example.com`, then your application redirect URL should be `http://bytebase.example.com/oidc/callback`.
13+
14+
</Info>
15+
16+
## Step 1: Create App Registration
17+
18+
1. Navigate to [Azure Portal](https://portal.azure.com)
19+
2. Go to **Microsoft Entra ID** (formerly **Azure Active Directory**) → **App registrations**
20+
3. Click **New registration**
21+
4. Configure the application:
22+
- **Name**: `Bytebase SSO` (or your preferred name)
23+
- **Supported account types**: Choose based on your requirements (single or multi-tenant)
24+
- **Redirect URI**:
25+
- Platform: `Web`
26+
- URI: `https://your-bytebase-domain.com/oidc/callback`
27+
5. Click **Register**
28+
29+
## Step 2: Configure Authentication
30+
31+
1. In your app registration, go to **Authentication**
32+
2. Verify your redirect URI under **Platform configurations**
33+
3. Under **Implicit grant and hybrid flows**:
34+
- Check **ID tokens** (used for implicit and hybrid flows)
35+
4. Click **Save**
36+
37+
## Step 3: Configure API Permissions
38+
39+
1. Go to **API permissions**
40+
2. Click **Add a permission** → **Microsoft Graph** → **Delegated permissions**
41+
3. Add the following permissions:
42+
43+
- `openid` (Sign users in)
44+
- `profile` (View users' basic profile)
45+
- `email` (View users' email address)
46+
- `offline_access` (Maintain access to data)
47+
- `User.Read` (Sign in and read user profile)
48+
- `GroupMember.Read.All` (Read group memberships) - **Required for group syncing**
49+
50+
4. Click **Add permissions**
51+
5. If required by your organization, click **Grant admin consent**
52+
53+
## Step 4: Configure Group Claims
54+
55+
For group synchronization to work, configure group claims:
56+
57+
1. Go to **Token configuration**
58+
2. Click **Add groups claim**
59+
3. Configure the groups claim:
60+
61+
- **Select group types**: Choose **Security groups**
62+
- **Customize token properties**:
63+
- For **ID**: Select `Group ID` (returns GUIDs) or `Cloud-only group display names` (returns readable names)
64+
- For better control, select **Groups assigned to the application**
65+
66+
4. Click **Add**
67+
68+
## Step 5: Create Client Secret
69+
70+
1. Go to **Certificates & secrets**
71+
2. Click **New client secret**
72+
3. Add description: `Bytebase OIDC`
73+
4. Select expiration period (recommend 24 months)
74+
5. Click **Add**
75+
6. **Important**: Copy the secret value immediately (it won't be shown again)
76+
77+
## Step 6: Gather Configuration Information
78+
79+
From the **Overview** page, collect:
80+
81+
- **Application (client) ID**: Your client ID
82+
- **Directory (tenant) ID**: Your tenant ID
83+
84+
Construct the issuer URL:
85+
86+
```text
87+
https://login.microsoftonline.com/{tenant-id}/v2.0
88+
```
89+
90+
## Step 7: Configure Bytebase OIDC
91+
92+
1. Log into Bytebase as an admin
93+
2. Navigate to **Settings** → **SSO** → **Create**
94+
3. Select **OIDC** as the provider type
95+
4. Configure with the following settings:
96+
97+
**Basic Information:**
98+
99+
- **Name**: `Entra ID`
100+
- **Identity Provider ID**: `entra-id`
101+
- **Domain**: Your organization domain (optional)
102+
103+
**Identity Provider Information:**
104+
105+
- **Issuer**: `https://login.microsoftonline.com/{your-tenant-id}/v2.0`
106+
- **Client ID**: Your application client ID
107+
- **Client Secret**: Your client secret
108+
- **Scopes**: `openid profile email offline_access`
109+
110+
**User Information Field Mapping:**
111+
112+
- **Email**: `email`
113+
- **Display Name**: `name`
114+
- **Groups**: `groups` (Important for group syncing)
115+
116+
5. Click **Create**
117+
118+
## Step 8: Test the Configuration
119+
120+
1. Click **Test Connection** in Bytebase
121+
2. You should be redirected to Microsoft login
122+
3. After successful authentication, verify:
123+
- User information is correctly mapped
124+
- Groups are being returned (if configured)
125+
126+
## Group Synchronization
127+
128+
If you configured group claims, Bytebase will automatically sync user groups:
129+
130+
1. Go to **Settings** → **Groups** in Bytebase
131+
2. Create groups that match your Entra ID groups:
132+
- If using Group IDs, create groups with GUID names
133+
- If using display names, create groups with matching names
134+
3. Assign appropriate roles to these groups
135+
136+
Users will be automatically added to matching Bytebase groups upon login.
137+
138+
## Example Group Synchronization Flow
139+
140+
1. User logs in via Entra ID
141+
2. ID token includes groups claim: `["c80adaad-11c0-4ad9-aa31-7ef37029aa2a", "6525b949-f790-4807-bf85-707fa6ec4cb4"]`
142+
3. Bytebase receives and processes groups
143+
4. User is automatically added to matching Bytebase groups
144+
5. User receives permissions based on group membership
145+
146+
## Troubleshooting
147+
148+
### Groups Not Appearing
149+
150+
1. **Check Token Configuration**: Ensure groups claim is added for ID tokens
151+
2. **Verify Permissions**: Ensure `GroupMember.Read.All` permission is granted
152+
3. **Check Group Types**: Verify users are members of security groups
153+
4. **Enable Debug Logging**: Run Bytebase with `--debug` flag to see claim details
154+
155+
### Common Issues
156+
157+
1. **Groups showing as GUIDs**: This is normal when using Group ID format
158+
2. **Missing groups**: Ensure groups are assigned to the application if using that filter
159+
3. **Token size limitations**: Consider using "Groups assigned to the application" for users with many groups
160+
161+
## Reference
162+
163+
- [Microsoft identity platform and OpenID Connect protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc)
164+
- [Configure group claims for applications](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims)

‎mintlify/administration/sso/overview.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Bytebase supports the following standard protocols that provide SSO:
88

99
- [OAuth 2.0](/administration/sso/oauth2)
1010
- [OpenID Connect (OIDC)](/administration/sso/oidc)
11+
- [Microsoft Entra ID (Azure AD) OIDC](/administration/sso/oidc-entra-id)
1112
- [Lightweight Directory Access Protocol (LDAP)](/administration/sso/ldap)
1213

1314
## Prerequisites

‎mintlify/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@
195195
"administration/sso/overview",
196196
"administration/sso/oauth2",
197197
"administration/sso/oidc",
198+
"administration/sso/oidc-entra-id",
198199
"administration/sso/ldap"
199200
]
200201
},

0 commit comments

Comments
 (0)