OAuth 2.0

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. GitHub will be shown as Sign in with GitHub)
• Identity Provider ID: a human-readable unique string, only lower-case alphabets and hyphens are allowed (e.g. github)
• Domain: the domain name to scope associated users (e.g. github.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. In order to know how to map the user information from an provider into Bytebase user fields, you need to fill the user information mapping form.

Bytebase will use the mapping to import the user profile fields when creating new accounts. The most important user field mapping is the identifier which is used to identify 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.

GitHub#

1. Follow Creating an OAuth App in GitHub to create an OAuth app in GitHub.

   

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.

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.

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.

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.