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).

Configuration#

Basic information:

• Name: the display name shown to your users (e.g. Google will be shown as Sign in with Google)
• Identity Provider ID: a human-readable unique string, only lower-case alphabets and hyphens are allowed (e.g. google)
• Domain: the domain name to scope associated users (e.g. google.com, optional)

Identity provider information:

• Issuer: the issuer of the response (e.g. https://accounts.google.com)
• Client ID: the client ID of your application
• Client secret: the client secret of your application
• Scopes: the scopes to request from the identity provider (e.g., openid, profile, email). Some providers also support a groups claim, which can be included by adding the groups scope. This is useful if you want to enable group syncing as part of the authentication process.

User information field mapping:

• Email: the claims field to be used as the Bytebase user email address (e.g. email)
• Display name: the claims field to be used as the Bytebase user display name (e.g. name, optional)
• Phone: the claims field to be used as the Bytebase user phone number (e.g. phone, optional)
• Groups: the claims field to be used as the Bytebase user groups (e.g. groups, optional). If this field is set, Bytebase will automatically perform group syncing by default.

Google#

1. Follow the Google OpenID Connect documentation to create a new OAuth client ID with "Web application" as the Application type.
2. Configure the Authorized redirect URIs to be {EXTERNAL_URL}/oidc/callback.
3. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: Google
   • Identity Provider ID: google
   • Domain: google.com
   • Issuer: https://accounts.google.com
   • Client ID: the client ID of your application
   • Client secret: the client secret of your application
   • Email: email
   • Display name: name

GitLab#

1. Follow the documentation of configure GitLab as an OAuth 2.0 authentication identity provider to create a new OAuth application:
   1. Configure the Scopes to include openid, profile and email.
   2. Configure the Redirect URI to be {EXTERNAL_URL}/oidc/callback.
2. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: GitLab
   • Identity Provider ID: gitlab
   • Domain: gitlab.acme.com
   • Issuer: https://gitlab.acme.com
   • Client ID: the application ID of your application
   • Client secret: the secret of your application
   • Email: email
   • Display name: name

Okta#

1. Follow the Okta create OIDC app integrations documentation to create a new OIDC app integration with "Web Application" as the Application type.
   1. Configure the Sign-in redirect URIs to be {EXTERNAL_URL}/oidc/callback.
   2. Configure the Assignments > Controlled access to be Allow everyone in your organization to access.
2. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: Okta
   • Identity Provider ID: okta
   • Domain: acme.okta.com
   • Issuer: https://acme.okta.com
   • Client ID: the client ID of your application
   • Client secret: the client secret of your application
   • Email: email
   • Display name: name

Keycloak#

1. Follow the Keycloak create OIDC provider documentation to create a new "OpenID Connect" client.
   1. Configure the Client ID to be bytebase.
   2. Configure the Valid redirect URIs to be {EXTERNAL_URL}/oidc/callback.
   3. Turn on the Capability config > Client authentication for the Credentials tab to be available (which will generate and display the client secret).
      1. In some older versions, configure Access Type to "confidential" instead.
2. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: Keycloak
   • Identity Provider ID: keycloak
   • Domain: keycloak.acme.com
   • Issuer: https://keycloak.acme.com/auth/realms/master
   • Client ID: bytebase
   • Client secret: the client secret of your application
   • Email: email
   • Display name: name

Casdoor#

1. Follow the Casdoor Casdoor documentation to create a new application.
   1. Configure the Client ID and Client secret to be bytebase.
   2. Configure the Valid redirect URIs to be {EXTERNAL_URL}/oidc/callback.
2. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: Casdoor
   • Identity Provider ID: casdoor
   • Domain: <your casdoor host>
   • Issuer: <your casdoor host>
   • Client ID: the client id of your application
   • Client secret: the client secret of your application
   • Email: email
   • Display name: name

Authing#

1. Follow the Authing 创建自建应用 to create a new "标准 Web 应用" as "自建应用".
   1. In 应用配置, configure the 登录回调 URL to be {EXTERNAL_URL}/oidc/callback.
   2. In 协议配置, configure the id_token 签名算法 to be RS256.
2. In Bytebase, go to Settings > SSO to create a new OIDC provider (all values are examples):
   • Name: Authing
   • Identity Provider ID: authing
   • Domain: acme.authing.cn
   • Issuer: https://acme.authing.cn/oidc
   • Client ID: the app ID of your application
   • Client secret: the app secret of your application
   • Email: email
   • Display name: name

Group Syncing#

Bytebase supports syncing identity provider (IdP) groups with Bytebase user groups for providers that include a groups claim in their tokens.

Group syncing is based on a one-to-one match using the group title. When a user logs in, Bytebase compares the group names from the IdP with existing Bytebase user group titles. If a match is found, the user is automatically added as a Member to the corresponding Bytebase user group.

To ensure security and consistency, Bytebase also automatically removes the user from any Bytebase groups that are not present in their IdP group claims.

Group syncing occurs during login, so if group membership changes in your IdP, users must log out and log back in for the changes to take effect.

Some OIDC providers like Okta support the groups claim, but you’ll need to first customize the tokens returned from Okta to include the groups claim. For more information, refer to Customize tokens returned from Okta with a groups claim.

Troubleshoot#

CORS#

If you click the login button and there is no response. It could be you are hitting the CORS error. You can verify this by inspecting the browser network. Please ask your network admin to whitelist Bytebase host. Alternatively, you can configure OAuth.