is only available with an active Enterprise license. Please add your license key to activate it.

You can connect Sourcebot to various external identity providers to associate a Sourcebot user with one or more external service accounts (ex. Google, GitHub, etc). External identity providers can be used for authentication and/or permission syncing. They’re defined in the config file in the top-level identityProviders object:

Example config with both google and github identity providers defined

{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "identityProviders": [
        {
            "provider": "github",
            "purpose": "account_linking",
            "accountLinkingRequired": true,
            "clientId": {
                "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_ID"
            },
            "clientSecret": {
                "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_SECRET"
            }
        },
        {
            "provider": "google",
            "clientId": {
                "env": "GOOGLE_IDENTITY_PROVIDER_CLIENT_ID"
            },
            "clientSecret": {
                "env": "GOOGLE_IDENTITY_PROVIDER_CLIENT_SECRET"
            }
        }
    ]
}

Secret values (such as clientId and clientSecret) can be provided as environment variables or Google Cloud secrets via tokens.

Supported External Identity Providers

Sourcebot uses Auth.js to connect to external identity providers. If there’s a provider supported by Auth.js that you don’t see below, please submit a feature request to have it added.

GitHub

Auth.js GitHub Provider Docs A GitHub connection can be used for authentication and/or permission syncing. This is controlled using the purpose field in the GitHub identity provider config.

instructions

To begin, you must register an Oauth client in GitHub to facilitate the identity provider connection. You can do this by creating a GitHub App or a GitHub OAuth App. Either one works, but the GitHub App is the recommended mechanism.The result of registering an OAuth client is a CLIENT_ID and CLIENT_SECRET which you’ll provide to Sourcebot.

GitHub App
GitHub OAuth App

You don’t need to install the app to use it as an external identity provider

Follow this guide to register a new GitHub App.When asked to provide a callback url, provide <sourcebot_url>/api/auth/callback/github (ex. https://sourcebot.coolcorp.com/api/auth/callback/github)Set the following fine-grained permissions in the GitHub App:

“Email addresses” account permissions (read)
"Metadata" repository permissions (read) (only needed if using permission syncing)

Follow this guide by GitHub to create an OAuth App.When asked to provide a callback url, provide <sourcebot_url>/api/auth/callback/github (ex. https://sourcebot.coolcorp.com/api/auth/callback/github)If permission syncing is enabled, also enable the repo scope.

Define environment variables

To provide Sourcebot the client id and secret for your OAuth client you must set them as environment variables. These can be named whatever you like (ex. GITHUB_IDENTITY_PROVIDER_CLIENT_ID and GITHUB_IDENTITY_PROVIDER_CLIENT_SECRET)

Define the identity provider config

Finally, pass the client id and secret to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "github",
             // "sso" for auth + perm sync, "account_linking" for only perm sync
             "purpose": "account_linking",
             // if purpose == "account_linking" this controls if a user must connect to the IdP
             "accountLinkingRequired": true,
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             }
         }
     ]
 }

GitLab

Auth.js GitLab Provider Docs A GitLab connection can be used for authentication and/or permission syncing. This is controlled using the purpose field in the GitLab identity provider config.

instructions

To begin, you must register an OAuth application in GitLab to facilitate the identity provider connection.Follow this guide by GitLab to create an OAuth application.When configuring your application:

Set the callback URL to <sourcebot_url>/api/auth/callback/gitlab (ex. https://sourcebot.coolcorp.com/api/auth/callback/gitlab)
Enable the read_user scope
If permission syncing is enabled, also enable the read_api scope

The result of registering an OAuth application is an APPLICATION_ID (CLIENT_ID) and SECRET (CLIENT_SECRET) which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id and secret for your OAuth application you must set them as environment variables. These can be named whatever you like (ex. GITLAB_IDENTITY_PROVIDER_CLIENT_ID and GITLAB_IDENTITY_PROVIDER_CLIENT_SECRET)

Define the identity provider config

Finally, pass the client id and secret to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "gitlab",
             // "sso" for auth + perm sync, "account_linking" for only perm sync
             "purpose": "account_linking",
             // if purpose == "account_linking" this controls if a user must connect to the IdP
             "accountLinkingRequired": true,
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             },
             // Optional: for self-hosted GitLab instances
             "baseUrl": "https://gitlab.example.com"
         }
     ]
 }

Bitbucket Cloud

Auth.js Bitbucket Provider Docs A Bitbucket Cloud connection can be used for authentication and/or permission syncing. This is controlled using the purpose field in the Bitbucket Cloud identity provider config.

instructions

To begin, you must register an OAuth consumer in Bitbucket to facilitate the identity provider connection.Navigate to your Bitbucket workspace settings at https://bitbucket.org/<your-workspace>/workspace/settings/api and create a new OAuth consumer under the OAuth consumers section.When configuring your consumer:

Set the callback URL to <sourcebot_url>/api/auth/callback/bitbucket-cloud (ex. https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-cloud)
Enable Account: Read
If permission syncing is enabled, also enable Repositories: Read

The result of creating an OAuth consumer is a Key (CLIENT_ID) and Secret (CLIENT_SECRET) which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id and secret for your OAuth consumer you must set them as environment variables. These can be named whatever you like (ex. BITBUCKET_CLOUD_IDENTITY_PROVIDER_CLIENT_ID and BITBUCKET_CLOUD_IDENTITY_PROVIDER_CLIENT_SECRET)

Define the identity provider config

Finally, pass the client id and secret to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "bitbucket-cloud",
             // "sso" for auth + perm sync, "account_linking" for only perm sync
             "purpose": "account_linking",
             // if purpose == "account_linking" this controls if a user must connect to the IdP
             "accountLinkingRequired": true,
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             }
         }
     ]
 }

Bitbucket Server

A Bitbucket Server (Data Center) connection can be used for authentication and/or permission syncing. This is controlled using the purpose field in the Bitbucket Server identity provider config.

instructions

To begin, you must register an OAuth 2.0 application in your Bitbucket Server instance to facilitate the identity provider connection.In your Bitbucket Server admin panel, navigate to Administration → Application Links and create a new incoming external application link.When configuring your application:

Set the redirect URL to <sourcebot_url>/api/auth/callback/bitbucket-server (ex. https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-server)
If permission syncing is enabled, also enable the REPO_READ scope

The result of creating the application is a CLIENT_ID and CLIENT_SECRET which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id and secret for your OAuth application you must set them as environment variables. These can be named whatever you like (ex. BITBUCKET_SERVER_IDENTITY_PROVIDER_CLIENT_ID and BITBUCKET_SERVER_IDENTITY_PROVIDER_CLIENT_SECRET)

Define the identity provider config

Finally, pass the client id, client secret, and your Bitbucket Server base URL to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "bitbucket-server",
             // "sso" for auth + perm sync, "account_linking" for only perm sync
             "purpose": "account_linking",
             // if purpose == "account_linking" this controls if a user must connect to the IdP
             "accountLinkingRequired": true,
             "baseUrl": "https://bitbucket.example.com",
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             }
         }
     ]
 }

Google

Auth.js Google Provider Docs A Google connection can be used for authentication.

instructions

To begin, you must register an OAuth client in Google Cloud Console to facilitate the identity provider connection.Follow this guide by Google to create OAuth 2.0 credentials.When configuring your OAuth client:

Set the application type to “Web application”
Add <sourcebot_url>/api/auth/callback/google to the authorized redirect URIs (ex. https://sourcebot.coolcorp.com/api/auth/callback/google)

The result of creating OAuth credentials is a CLIENT_ID and CLIENT_SECRET which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id and secret for your OAuth client you must set them as environment variables. These can be named whatever you like (ex. GOOGLE_IDENTITY_PROVIDER_CLIENT_ID and GOOGLE_IDENTITY_PROVIDER_CLIENT_SECRET)

Define the identity provider config

Finally, pass the client id and secret to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "google",
             "purpose": "sso",
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             }
         }
     ]
 }

Okta

Auth.js Okta Provider Docs An Okta connection can be used for authentication.

instructions

To begin, you must register an OAuth application in Okta to facilitate the identity provider connection.Follow this guide by Okta to create an OAuth application.When configuring your application:

Set the application type to “Web Application”
Add <sourcebot_url>/api/auth/callback/okta to the sign-in redirect URIs (ex. https://sourcebot.coolcorp.com/api/auth/callback/okta)

The result of creating an OAuth application is a CLIENT_ID, CLIENT_SECRET, and ISSUER URL which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id, client secret, and issuer for your OAuth application you must set them as environment variables. These can be named whatever you like (ex. OKTA_IDENTITY_PROVIDER_CLIENT_ID, OKTA_IDENTITY_PROVIDER_CLIENT_SECRET, and OKTA_IDENTITY_PROVIDER_ISSUER)

Define the identity provider config

Finally, pass the client id, client secret, and issuer to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "okta",
             "purpose": "sso",
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             },
             "issuer": {
                 "env": "YOUR_ISSUER_ENV_VAR"
             }
         }
     ]
 }

Keycloak

Auth.js Keycloak Provider Docs A Keycloak connection can be used for authentication.

instructions

To begin, you must register an OAuth client in Keycloak to facilitate the identity provider connection.Follow this guide by Keycloak to create an OpenID Connect client.When configuring your client:

Set the client protocol to “openid-connect”
Set the access type to “confidential”
Add <sourcebot_url>/api/auth/callback/keycloak to the valid redirect URIs (ex. https://sourcebot.coolcorp.com/api/auth/callback/keycloak)

The result of creating an OAuth client is a CLIENT_ID, CLIENT_SECRET, and an ISSUER URL (typically in the format https://<keycloak-domain>/realms/<realm-name>) which you’ll provide to Sourcebot.

Define environment variables

To provide Sourcebot the client id, client secret, and issuer for your OAuth client you must set them as environment variables. These can be named whatever you like (ex. KEYCLOAK_IDENTITY_PROVIDER_CLIENT_ID, KEYCLOAK_IDENTITY_PROVIDER_CLIENT_SECRET, and KEYCLOAK_IDENTITY_PROVIDER_ISSUER)

Define the identity provider config

Finally, pass the client id, client secret, and issuer to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "keycloak",
             "purpose": "sso",
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             },
             "issuer": {
                 "env": "YOUR_ISSUER_ENV_VAR"
             }
         }
     ]
 }

Microsoft Entra ID

Auth.js Microsoft Entra ID Provider Docs A Microsoft Entra ID connection can be used for authentication.

instructions

To begin, you must register an OAuth application in Microsoft Entra ID (formerly Azure Active Directory) to facilitate the identity provider connection.Follow this guide by Microsoft to register an application.When configuring your application:

Under “Authentication”, add a platform and select “Web”
Set the redirect URI to <sourcebot_url>/api/auth/callback/microsoft-entra-id (ex. https://sourcebot.coolcorp.com/api/auth/callback/microsoft-entra-id)
Under “Certificates & secrets”, create a new client secret

The result of registering an application is a CLIENT_ID (Application ID), CLIENT_SECRET, and TENANT_ID which you’ll use to construct the issuer URL.

Define environment variables

To provide Sourcebot the client id, client secret, and issuer for your OAuth application you must set them as environment variables. These can be named whatever you like (ex. MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_CLIENT_ID, MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_CLIENT_SECRET, and MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_ISSUER)The issuer URL should be in the format: https://login.microsoftonline.com/<TENANT_ID>/v2.0

Define the identity provider config

Finally, pass the client id, client secret, and issuer to Sourcebot by defining a identityProvider object in the config file:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "microsoft-entra-id",
             "purpose": "sso",
             "clientId": {
                 "env": "YOUR_CLIENT_ID_ENV_VAR"
             },
             "clientSecret": {
                 "env": "YOUR_CLIENT_SECRET_ENV_VAR"
             },
             "issuer": {
                 "env": "YOUR_ISSUER_ENV_VAR"
             }
         }
     ]
 }

Authentik

Auth.js Authentik Provider Docs An Authentik connection can be used for authentication.

instructions

Create a OAuth2/OpenID Connect application

To begin, you must create a OAuth2/OpenID Connect application in Authentik. For more information, see the Authentik documentation.When configuring your application:

Set the provider type to “OAuth2/OpenID Connect”
Set the client type to “Confidential”
Add <sourcebot_url>/api/auth/callback/authentik to the redirect URIs (ex. https://sourcebot.coolcorp.com/api/auth/callback/authentik)

After creating the application, open the application details to obtain the client id, client secret, and issuer URL (typically in the format https://<authentik-domain>/application/o/<provider-slug>/).

Define environment variables

The client id, secret, and issuer URL are provided to Sourcebot via environment variables. These can be named whatever you like (ex. AUTHENTIK_IDENTITY_PROVIDER_CLIENT_ID, AUTHENTIK_IDENTITY_PROVIDER_CLIENT_SECRET, and AUTHENTIK_IDENTITY_PROVIDER_ISSUER)

Define the identity provider config

Create a identityProvider object in the config file with the following fields:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "authentik",
             "purpose": "sso",
             "clientId": {
                 "env": "AUTHENTIK_IDENTITY_PROVIDER_CLIENT_ID"
             },
             "clientSecret": {
                 "env": "AUTHENTIK_IDENTITY_PROVIDER_CLIENT_SECRET"
             },
             "issuer": {
                 "env": "AUTHENTIK_IDENTITY_PROVIDER_ISSUER"
             }
         }
     ]
 }

JumpCloud

A JumpCloud connection can be used for authentication. JumpCloud supports OIDC (OpenID Connect), which Sourcebot uses to authenticate users.

instructions

Create an SSO Application in JumpCloud

To begin, you must create an SSO application in JumpCloud to facilitate the identity provider connection. For more information, see the JumpCloud OIDC documentation.When configuring your application:

Set the SSO type to “OIDC”
Add <sourcebot_url>/api/auth/callback/jumpcloud to the redirect URIs (ex. https://sourcebot.coolcorp.com/api/auth/callback/jumpcloud)
Set the login URL to <sourcebot_url>/login

After creating the application, note the CLIENT_ID and CLIENT_SECRET. The issuer URL is typically https://oauth.id.jumpcloud.com.

Define environment variables

The client id, secret, and issuer URL are provided to Sourcebot via environment variables. These can be named whatever you like (ex. JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_ID, JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_SECRET, and JUMPCLOUD_IDENTITY_PROVIDER_ISSUER)

Define the identity provider config

Create a identityProvider object in the config file with the following fields:

 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
     "identityProviders": [
         {
             "provider": "jumpcloud",
             "purpose": "sso",
             "clientId": {
                 "env": "JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_ID"
             },
             "clientSecret": {
                 "env": "JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_SECRET"
             },
             "issuer": {
                 "env": "JUMPCLOUD_IDENTITY_PROVIDER_ISSUER"
             }
         }
     ]
 }

Getting Started

Features

API Reference

Configuration

Upgrade

External Identity Providers

Supported External Identity Providers

GitHub

GitLab

Bitbucket Cloud

Bitbucket Server

Google

Okta

Keycloak

Microsoft Entra ID

Authentik

JumpCloud

Getting Started

Features

API Reference

Configuration

Upgrade

​Supported External Identity Providers

​GitHub

​GitLab

​Bitbucket Cloud

​Bitbucket Server

​Google

​Okta

​Keycloak

​Microsoft Entra ID

​Authentik

​JumpCloud

Supported External Identity Providers

GitHub

GitLab

Bitbucket Cloud

Bitbucket Server

Google

Okta

Keycloak

Microsoft Entra ID

Authentik

JumpCloud