> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  For **Microsoft Entra ID (Azure AD)**, see the dedicated [Entra ID OIDC guide](/administration/sso/oidc-entra-id) which covers app registration, API permissions, group claims, and troubleshooting.
</Tip>

## Configuration

<Info>
  1. Please make sure the [`--external-url`](/get-started/self-host/external-url) is configured correctly for the Bytebase workspace.

     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](https://openid.net/specs/openid-connect-discovery-1_0.html) endpoint to find the correct value, e.g. `https://acme.okta.com/.well-known/openid-configuration`.
</Info>

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**](#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**](#group-syncing) by default.

### Google

1. Follow the Google [OpenID Connect documentation](https://developers.google.com/identity/openid-connect/openid-connect) 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](https://docs.gitlab.com/ee/integration/oauth_provider.html) 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`

<Note>
  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.
</Note>

### Okta

1. Follow the Okta [create OIDC app integrations documentation](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm) 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](https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-clients_server_administration_guide) 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](https://casdoor.org/docs/basic/core-concepts) 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 [创建自建应用](https://docs.authing.cn/v2/guides/app-new/create-app/create-app.html) 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](/administration/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 the [Okta documentation](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/).

## 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](https://developer.chrome.com/docs/devtools/network).
Please ask your network admin to whitelist Bytebase host. Alternatively, you can configure [OAuth](/administration/sso/oauth2/).