Please make sure the
--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
- Navigate to Azure Portal
- Go to Microsoft Entra ID (formerly Azure Active Directory) → App registrations
- Click New registration
- 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
- Platform:
- Name:
- Click Register
Step 2: Configure Authentication
- In your app registration, go to Authentication
- Verify your redirect URI under Platform configurations
- Under Implicit grant and hybrid flows:
- Check ID tokens (used for implicit and hybrid flows)
- Click Save
Step 3: Configure API Permissions
- Go to API permissions
- Click Add a permission → Microsoft Graph → Delegated permissions
-
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
- Click Add permissions
- If required by your organization, click Grant admin consent
Step 4: Configure Group Claims
For group synchronization to work, configure group claims:- Go to Token configuration
- Click Add groups claim
-
Configure the groups claim:
- Select group types: Choose Security groups
- Customize token properties:
- For ID: Select
Group ID
(returns GUIDs) orCloud-only group display names
(returns readable names)
- For ID: Select
- For better control, select Groups assigned to the application
- Click Add
Step 5: Create Client Secret
- Go to Certificates & secrets
- Click New client secret
- Add description:
Bytebase OIDC
- Select expiration period (recommend 24 months)
- Click Add
- 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
Step 7: Configure Bytebase OIDC
- Log into Bytebase as an admin
- Navigate to Settings → SSO → Create
- Select OIDC as the provider type
- Configure with the following settings:
- Name:
Entra ID
- Identity Provider ID:
entra-id
- Domain: Your organization domain (optional)
- 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
- Email:
email
- Display Name:
name
- Groups:
groups
(Important for group syncing)
- Click Create
Step 8: Test the Configuration
- Click Test Connection in Bytebase
- You should be redirected to Microsoft login
- 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:- Go to Settings → Groups in Bytebase
- 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
- Assign appropriate roles to these groups
Example Group Synchronization Flow
- User logs in via Entra ID
- ID token includes groups claim:
["c80adaad-11c0-4ad9-aa31-7ef37029aa2a", "6525b949-f790-4807-bf85-707fa6ec4cb4"]
- Bytebase receives and processes groups
- User is automatically added to matching Bytebase groups
- User receives permissions based on group membership
Troubleshooting
Groups Not Appearing
- Check Token Configuration: Ensure groups claim is added for ID tokens
- Verify Permissions: Ensure
GroupMember.Read.All
permission is granted - Check Group Types: Verify users are members of security groups
- Enable Debug Logging: Run Bytebase with
--debug
flag to see claim details
Common Issues
- Groups showing as GUIDs: This is normal when using Group ID format
- Missing groups: Ensure groups are assigned to the application if using that filter
- Token size limitations: Consider using “Groups assigned to the application” for users with many groups