Authentication

Sourcegraph supports multiple authentication providers. Users need an account to access your instance, and the auth provider determines how accounts are created and verified. You can configure more than one provider — for example, SAML for SSO sign-in plus GitHub OAuth to prove code host identity for permission syncing. Authentication providers are configured in the auth.providers array in your site configuration. Go to Site admin > Configuration to edit this.

If you enable repository permissions, auth providers are also used to verify who a user is on the code host. For example, to see private GitHub repositories, a user must authenticate with the GitHub OAuth provider so Sourcegraph can map their Sourcegraph account to their GitHub account.

Choosing an auth provider

If you are unsure which provider to use:

No SSO / quick start: use builtin password auth. You can migrate later; email addresses link accounts automatically.
Behind an auth proxy (like oauth2_proxy or Google IAP): use http-header.
Indexing GitHub or GitLab: use the OAuth provider for that code host, even if the code host itself uses SAML externally.
Identity provider with SAML support: use saml.
Identity provider with OIDC support (Okta, Azure AD, Google Workspace, Auth0, Ping Identity): use openidconnect.

Auth provider configuration

The builtin provider manages usernames and passwords inside Sourcegraph. It is the default on a fresh install and the simplest option for teams without a corporate SSO system.

{
  "auth.providers": [
    {
      "type": "builtin",
      "allowSignup": false
    }
  ]
}

allowSignup

true — any user who can reach your instance can create an account.
false (recommended) — new users must be created by a site admin, or they can submit an access request that admins approve.

Account lockoutAccounts are locked for 30 minutes after 5 failed sign-in attempts within one hour. You can tune this:

{
  "auth.lockout": {
    "consecutivePeriod": 3600,
    "failedAttemptThreshold": 5,
    "lockoutPeriod": 1800
  }
}

To allow self-serve account unlock via email, add:

{
  "auth.unlockAccountLinkExpiry": 30,
  "auth.unlockAccountLinkSigningKey": "base64-encoded-signing-key"
}

Generate the signing key with ssh-keygen -t ed25519 -a 128 -f auth.unlockAccountLinkSigningKey && base64 auth.unlockAccountLinkSigningKey | tr -d '\n'.Password policyEnforce minimum length and complexity:

{
  "auth.minPasswordLength": 12,
  "auth.passwordPolicy": {
    "enabled": true,
    "numberOfSpecialCharacters": 1,
    "requireAtLeastOneNumber": true,
    "requireUpperandLowerCase": true
  }
}

Create a GitHub OAuth application (on GitHub.com, or on your GitHub Enterprise instance). Set:

Homepage URL: https://sourcegraph.example.com
Authorization callback URL: https://sourcegraph.example.com/.auth/github/callback

To sync organization membership for access control, create the OAuth app under your GitHub organization, or approve it for your organization after creation.

Add to site configuration:

{
  "auth.providers": [
    {
      "type": "github",
      "url": "https://github.example.com",
      "displayName": "GitHub",
      "clientID": "replace-with-the-oauth-client-id",
      "clientSecret": "replace-with-the-oauth-client-secret",
      "allowSignup": false,
      "allowOrgs": ["your-org-name"],
      "allowOrgsMap": { "orgName": ["Your Team Name"] }
    }
  ]
}

Leave url empty to use github.com.Access controls

Field	Description
`allowSignup`	`true` lets any GitHub user sign up. `false` (default) requires an admin to pre-create the account.
`allowOrgs`	Restrict sign-in to members of listed GitHub organizations.
`allowOrgsMap`	Restrict sign-in to members of specific teams within organizations. Use the team’s display name exactly.
`requiredSsoOrgs`	Require users to have SAML SSO authorization for specific GitHub org IDs (numeric). Use `["all"]` to require authorization for all organizations.

If allowSignup: true and allowOrgs is not set, anyone with a GitHub account and network access to your instance can sign up.

Create a GitLab OAuth application. Set:

Authorization callback URL: https://sourcegraph.example.com/.auth/gitlab/callback
Scopes: read_user, api (write access is required for Batch Changes)

Add to site configuration:

{
  "auth.providers": [
    {
      "type": "gitlab",
      "displayName": "GitLab",
      "clientID": "replace-with-the-oauth-application-id",
      "clientSecret": "replace-with-the-oauth-secret",
      "url": "https://gitlab.example.com",
      "allowSignup": false,
      "allowGroups": ["group", "group/subgroup"]
    }
  ]
}

Access controls

Field	Description
`allowSignup`	Defaults to `true` for GitLab (unlike GitHub). Set `false` to require admin-created accounts.
`allowGroups`	Restrict sign-in to members of listed groups or subgroups. Use the full path from the URL, e.g. `group/subgroup/subsubgroup`. Users need at least `Guest` access level.
`ssoURL`	If your GitLab group requires SAML/SSO, add the group SSO URL here so users are redirected correctly.
`syncInternalRepoPermissions`	Set `false` to skip syncing permissions for internal repositories (useful if internal repos are public to everyone on GitLab).

GitLab administrators who sign in to Sourcegraph do not automatically get access to all repositories — only those where they have the Reporter role or higher.

SAML authentication delegates sign-in to a SAML Identity Provider (IdP). Sourcegraph acts as the Service Provider (SP).Supported identity providers include Okta, Microsoft Entra ID (Azure AD), Microsoft ADFS, Auth0, OneLogin, Ping Identity, Salesforce Identity, and JumpCloud.

Sourcegraph supports at most one SAML provider at a time. You can configure additional providers of other types alongside it.

Step 1: Ensure externalURL is set in site config and matches the URL you configure in your IdP exactly (same scheme, no trailing slash):

{
  "externalURL": "https://sourcegraph.example.com"
}

Step 2: Register Sourcegraph as a SAML application in your IdP. The ACS (Assertion Consumer Service) URL is:

https://sourcegraph.example.com/.auth/saml/acs

Step 3: Add the SAML provider to auth.providers:

{
  "auth.providers": [
    {
      "type": "saml",
      "configID": "okta",
      "identityProviderMetadataURL": "https://your-idp.example.com/saml-metadata"
    }
  ]
}

If your IdP does not expose a metadata URL, use identityProviderMetadata with the raw XML string instead.Access controls

Field	Description
`allowSignup`	Defaults to `true`. Set `false` to require admin-created accounts.
`allowGroups`	Restrict sign-in to members of listed SAML groups. The SAML assertion must return a list of group strings.
`groupsAttributeName`	Name of the SAML assertion attribute that contains group membership. Defaults to `"groups"`.
`usernameAttributeNames`	Ordered list of SAML attributes to use when constructing the Sourcegraph username for new users.

Email or NameID changes in the IdP are not automatically reflected in Sourcegraph. Admins can manually update a user’s email at https://sourcegraph.example.com/users/<user>/settings/emails.

The openidconnect provider supports any IdP that implements OpenID Connect, including:

Google Workspace
Okta
Microsoft Entra ID (Azure AD)
Auth0
Ping Identity
Salesforce Identity

Required OIDC scopes: openid, email, profile.Step 1: Create an OIDC client in your IdP. Set the redirect/callback URI to:

https://sourcegraph.example.com/.auth/callback

Step 2: Add to site configuration:

{
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "openidconnect",
      "issuer": "https://oidc.example.com",
      "clientID": "my-client-id",
      "clientSecret": "my-client-secret",
      "configID": "my-config-id",
      "requireEmailDomain": "example.com",
      "allowSignup": false
    }
  ]
}

Sourcegraph uses OIDC Discovery to read provider metadata from https://oidc.example.com/.well-known/openid-configuration.Google Workspace exampleCreate an OAuth client in the Google API credentials console:

Application type: Web application
Authorized redirect URI: https://sourcegraph.example.com/.auth/callback

{
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "openidconnect",
      "issuer": "https://accounts.google.com",
      "clientID": "my-client-id",
      "clientSecret": "my-client-secret",
      "requireEmailDomain": "example.com"
    }
  ]
}

Set requireEmailDomain to your organization’s domain to prevent sign-ins from personal Google accounts.

Use this provider when Sourcegraph is behind an authentication proxy such as oauth2_proxy or Google Identity-Aware Proxy (IAP). The proxy handles authentication and passes the user’s identity to Sourcegraph via HTTP headers.

{
  "auth.providers": [
    {
      "type": "http-header",
      "usernameHeader": "X-Forwarded-User",
      "emailHeader": "X-Forwarded-Email"
    }
  ]
}

Replace X-Forwarded-User with the header your proxy sets.

Ensure the proxy does not forward its own Authorization header to Sourcegraph. For oauth2_proxy, use -pass-basic-auth false.

Username header prefixesSome proxies prefix the username. For example, Google IAP sets x-goog-authenticated-user-id to accounts.google.com:alice. Use stripUsernameHeaderPrefix to remove it:

{
  "auth.providers": [
    {
      "type": "http-header",
      "usernameHeader": "x-goog-authenticated-user-email",
      "stripUsernameHeaderPrefix": "accounts.google.com:"
    }
  ]
}

How account linking works

Sourcegraph links accounts across providers by matching verified email addresses. When a user signs in with a new provider, if their email matches an existing Sourcegraph account, the accounts are linked. If there is no match and allowSignup is enabled, a new account is created. Usernames from external providers are normalized: characters outside [a-zA-Z0-9-._] are replaced with -, and email-style usernames are truncated at @. For example, [email protected] becomes alice-smith.

Managing user accounts

Site admins can manage users at Site admin > Users:

Create users: Go to /site-admin/users/new to create accounts manually.
Deactivate users: Deactivated users cannot sign in but their data is retained.
Delete users: Permanently removes the account and all associated data.
Reset passwords: For builtin auth, admins can send password reset emails.

SCIM provisioning (beta)

SCIM (System for Cross-domain Identity Management) lets your identity provider automatically provision and deprovision Sourcegraph user accounts. To enable SCIM, set a shared secret token in site configuration:

{
  "scim.authToken": "your-scim-token",
  "scim.identityProvider": "STANDARD"
}

Use "scim.identityProvider": "Azure AD" if your IdP is Microsoft Entra ID (Azure AD). The SCIM endpoint is https://sourcegraph.example.com/.api/scim/v2. Configure this in your IdP’s enterprise application settings along with the auth token.

Session settings

Control how long user sessions remain valid:

{
  "auth.sessionExpiry": "2160h",
  "auth.maxSessionIdleDuration": "0"
}

auth.sessionExpiry: Maximum session duration (default: 90 days / 2160h). Must be at least 1 hour.
auth.maxSessionIdleDuration: If set, sessions expire after this period of inactivity. Defaults to no idle expiry.

Access tokens

Users can create personal access tokens for API and CLI access. Control this with:

{
  "auth.accessTokens": {
    "allow": "all-users-create",
    "allowNoExpiration": false,
    "defaultExpirationDays": 90
  }
}

Set "allow": "site-admin-create" to restrict token creation to site admins, or "allow": "none" to disable access tokens entirely.

Administration

Integrations & API

Choosing an auth provider

Auth provider configuration

How account linking works

Managing user accounts

SCIM provisioning (beta)

Session settings

Access tokens

Build docs developers (and LLMs) love

Administration

Integrations & API

​Choosing an auth provider

​Auth provider configuration

​How account linking works

​Managing user accounts

​SCIM provisioning (beta)

​Session settings

​Access tokens

Build docs developers (and LLMs) love

Choosing an auth provider

Auth provider configuration

How account linking works

Managing user accounts

SCIM provisioning (beta)

Session settings

Access tokens