OAuth is an open standard for token-based authentication and authorization which is used to provide Single Sign-On (SSO). Bytebase supports popular OAuth 2.0 providers (GitHub, Google, GitLab) and custom providers.

​
Overview

In the creating SSO dialog, you need to fill following fields:

​
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-fsgs)
  • Domain: the domain name to scope associated users (e.g. google.com, optional)

​
Identity provider information

The information is the base concept of OAuth 2.0 and comes from your provider.

  • Client ID is a public identifier of the custom provider;
  • Client Secret is the OAuth2 client secret from identity provider;
  • Auth URL is the custom provider’s OAuth2 login page address;
  • Scopes is the scope parameter carried when accessing the OAuth2 URL, which is filled in according to the custom provider;
  • Token URL is the API address for obtaining access token;
  • User information URL is the API address for obtaining user information by access token;
  • Auth style specifies how the endpoint wants the client ID & client secret sent.
    • In params: The client_id and client_secret will be sending in the POST body as application/x-www-form-urlencoded parameters.
    • In header: The client_id and client_secret will be sending in HTTP Basic Authorization. This is an optional style described in the OAuth2 RFC 6749 section 2.3.1.

​
User information mapping

For different providers, the structures returned by their user information API are usually not the same. That’s why you need to fill an information mapping form for mapping user information into Bytebase user fields.

Bytebase uses the mapping to import user profile fields when creating new accounts.

The most important information is Bytebase user's email. It identifies the Bytebase account associated with the OAuth 2.0 login.

  • Email is the field name of primary email in 3rd-party user info;
  • DisplayName is the field name of display name in 3rd-party user info (optional);
  • Phone: is the field name of phone number in 3rd-party user info (optional).

​
Built-in OAuth Provider

OAuth 2.0 usually requires an authorization callback url in the configuration. Please make sure the —external-url is set correctly.

If you start Bytebase with --external-url http://bytebase.example.com, then the authorization callback URL will be http://bytebase.example.com/oauth/callback.

Bytebase provides templates for configuring built-in OAuth providers.

​
Google

  1. Follow the Using OAuth 2.0 to Access Google APIs to create OAuth 2.0 client credentials in Google API Console.

  2. Open creating SSO dialog and select the Google template.

  3. Update the Client ID and Client secret fields with the OAuth 2.0 client credential you just created.

  4. After filling in all the required fields, try to click Test connection.

  5. If everything is OK, click the Create button.

​
GitHub

  1. Follow Creating an OAuth App in GitHub to create an OAuth app in GitHub, where you replace YOUR_EXTERNAL_URL in the image below with the external URL you configured in Bytebase Workspace.

  2. Open creating SSO dialog and select the GitHub template.

  3. Update the Client ID and Client secret fields with the GitHub OAuth App you just created.

  4. After filling in all the required fields, try to click Test connection.

  5. If everything is OK, click the Create button.

  6. Go to your GitHub Public profile, make sure your Public email is set to the email you intend to use for SSO. Otherwise, the SSO will not work.Add commentMore actions

​
GitLab

  1. Follow Configure GitLab as an OAuth 2.0 authentication identity provider to create an OAuth 2 application in GitLab.

  2. Open creating SSO dialog and select the GitLab template.

  3. Update the Client ID and Client secret fields with the GitLab OAuth 2 application you just created.

  4. After filling in all the required fields, try to click Test connection.

  5. If everything is OK, click the Create button.

​
Microsoft Entra (Azure AD)

  1. Follow the Register an application with the Microsoft identity platform to create an Application in Microsoft Entra admin center.

  2. Create a client secret in the Client credentials tab.

  3. Open creating SSO dialog and select the Microsoft Entra template.

  4. Update the Client ID, Client secret and the Endpoints fields with the OAuth 2.0 client credential you just created.

  5. After filling in all the required fields, try to click Test connection.

  6. If everything is OK, click the Create button.