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#

1. Please make sure the --external-url is configured correctly for the Bytebase instance.

   If your start Bytebase with --external-url http://bytebase.example.com, then your application redirect URL should be http://bytebase.example.com/oidc/callback.

2. If you're unsure about the Issuer of your IdP, you can always use the OpenID Connect Discovery endpoint to find the correct value, e.g. https://acme.okta.com/.well-known/openid-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

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)

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

In some GitLab self-hosted setups, the Issuer is http://gitlab.acme.com (HTTP) instead of https://gitlab.acme.com (HTTPS) despite the latter being the URL used to access the instance.

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

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.