From f781447a0bc1d2a1c848372ec7e2dac300711d3f Mon Sep 17 00:00:00 2001 From: msukkari Date: Mon, 3 Nov 2025 20:59:21 -0800 Subject: [PATCH] wip started idp docs --- docs/docs.json | 1 + docs/docs/configuration/idp.mdx | 125 ++++++++++++++++++++++++++++++++ docs/docs/license-key.mdx | 5 +- 3 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 docs/docs/configuration/idp.mdx diff --git a/docs/docs.json b/docs/docs.json index 3a2cb43f..441f4139 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -79,6 +79,7 @@ ] }, "docs/configuration/language-model-providers", + "docs/configuration/idp", { "group": "Authentication", "pages": [ diff --git a/docs/docs/configuration/idp.mdx b/docs/docs/configuration/idp.mdx new file mode 100644 index 00000000..f8edb811 --- /dev/null +++ b/docs/docs/configuration/idp.mdx @@ -0,0 +1,125 @@ +--- +title: External Identity Providers +sidebarTitle: External identity providers +--- + +import LicenseKeyRequired from '/snippets/license-key-required.mdx' + + + +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](/docs/configuration/auth) and/or [permission syncing](/docs/features/permission-syncing). They're defined in the +[config file](/docs/configuration/config-file) in the top-level `identityProviders` object: + +```json wrap icon="code" 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": "integration", + "required": true, +/* +Secrets are provided through environment variables. Set the secret into +an env var and provide the name here to tell Sourcebot where to get +the value +*/ + "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" + } + } + ] +} +``` + +# Supported External Identity Providers + +Sourcebot uses [Auth.js](https://authjs.dev/) 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](https://github.com/sourcebot-dev/sourcebot/issues) to have it added. + +### GitHub + +[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github) + +A GitHub connection can be used for either [authentication](/docs/configuration/auth) or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field +in the GitHub identity provider config. + + + + + 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 [modern way](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). + + + The result of registering an OAuth client is a `CLIENT_ID` and `CLIENT_SECRET` which you'll provide to Sourcebot. + + + You don't need to install the app to use it as an external identity provider + Follow [this guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to register a new GitHub App. + + When asked to provide a callback url, provide `/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)` + + + Follow [this guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) by GitHub to create an OAuth App. + + When asked to provide a callback url, provide `/api/auth/callback/github` (ex. https://sourcebot.coolcorp.com/api/auth/callback/github) + + + + + 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`) + + + Finally, pass the client id and secret to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): + + ```json wrap icon="code" + { + "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", + "identityProviders": [ + { + "provider": "github", + // "sso" for auth + perm sync, "integration" for only perm sync + "purpose": "integration", + // if purpose == "integration" this controls if a user must connect to the IdP + "required": true, + "clientId": { + "env": "YOUR_CLIENT_ID_ENV_VAR" + }, + "clientSecret": { + "env": "YOUR_CLIENT_SECRET_ENV_VAR" + } + } + ] + } + ``` + + + + +### GitLab + +### Google + +### Okta + +### Keycloak + +### Microsoft Entra ID + diff --git a/docs/docs/license-key.mdx b/docs/docs/license-key.mdx index 272eab62..4b13fcaf 100644 --- a/docs/docs/license-key.mdx +++ b/docs/docs/license-key.mdx @@ -7,7 +7,7 @@ sidebarTitle: License key If you'd like a trial license, [reach out](https://www.sourcebot.dev/contact) and we'll send one over within 24 hours -All core Sourcebot features are available [FSL licensed](https://github.com/sourcebot-dev/sourcebot/blob/main/LICENSE.md#functional-source-license-version-11-alv2-future-license) without any limits. Some additional features require a license key. See the [pricing page](https://www.sourcebot.dev/pricing) for more details. +All core Sourcebot features are available under the [FSL license](https://github.com/sourcebot-dev/sourcebot/blob/main/LICENSE.md#functional-source-license-version-11-alv2-future-license). Some additional features require a license key. See the [pricing page](https://www.sourcebot.dev/pricing) for more details. ## Activating a license key @@ -25,7 +25,7 @@ docker run \ ## Feature availability --- -| Feature | OSS | Licensed | +| Feature | [FSL](https://github.com/sourcebot-dev/sourcebot/blob/main/LICENSE.md#functional-source-license-version-11-alv2-future-license) | [Enterprise](https://github.com/sourcebot-dev/sourcebot/blob/main/ee/LICENSE) | |:---------|:-----|:----------| | [Search](/docs/features/search/syntax-reference) | ✅ | ✅ | | [Full code host support](/docs/connections/overview) | ✅ | ✅ | @@ -34,6 +34,7 @@ docker run \ | [Login with credentials](/docs/configuration/auth/overview) | ✅ | ✅ | | [Login with email codes](/docs/configuration/auth/overview) | ✅ | ✅ | | [Login with SSO](/docs/configuration/auth/overview#enterprise-authentication-providers) | 🛑 | ✅ | +| [Permission syncing](/docs/features/permission-syncing) | 🛑 | ✅ | | [Code navigation](/docs/features/code-navigation) | 🛑 | ✅ | | [Search contexts](/docs/features/search/search-contexts) | 🛑 | ✅ | | [Audit logs](/docs/configuration/audit-logs) | 🛑 | ✅ |