Skip to main content
This feature 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 either authentication or permission syncing. This is controlled using the purpose field in the GitHub identity provider config.
1

Register an Oauth Client

To begin, you must register an Oauth client in GitHub to faciliate 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)
2

Define environemnt 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)
3

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 either authentication or permission syncing. This is controlled using the purpose field in the GitLab identity provider config.
1

Register an OAuth Application

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:The result of registering an OAuth application is an APPLICATION_ID (CLIENT_ID) and SECRET (CLIENT_SECRET) which you’ll provide to Sourcebot.
2

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)
3

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"
         }
     ]
 }

​
Google

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

Register an OAuth Client

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:The result of creating OAuth credentials is a CLIENT_ID and CLIENT_SECRET which you’ll provide to Sourcebot.
2

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)
3

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.
1

Register an OAuth Application

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:The result of creating an OAuth application is a CLIENT_ID, CLIENT_SECRET, and ISSUER URL which you’ll provide to Sourcebot.
2

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)
3

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.
1

Register an OAuth Client

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: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.
2

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)
3

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.
1

Register an OAuth Application

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: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.
2

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
3

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"
             }
         }
     ]
 }