User authentication (SSO)

Sourcegraph supports the following ways for users to sign in:

The authentication provider is configured in the auth.providers site configuration option.

Guidance

If you are unsure which auth provider is right for you, we recommend applying the following rules in order:

  • If you have no external identity providers (i.e., not SSO) or are just trying to spin Sourcegraph up as quickly as possible to try, use builtin authentication. You can always change the auth configuration later, and user identities from external providers will be linked automatically to existing Sourcegraph accounts using verified email addresses.
  • If you are deploying Sourcegraph behind a HTTP authentication proxy service, use the http-header provider type. The proxy service should handle authentication and session management and, in turn, set a HTTP header that indicates the user identity to Sourcegraph.
  • If you are configuring Sourcegraph to index a GitHub or GitLab instance, we recommend using the OAuth provider for that code host. This applies even if the code host itself uses an external identity provider (e.g., SAML, OpenID Connect, LDAP, etc.). Sourcegraph will redirect to your code host on sign-in and the code host will perform the required sign-in flow before redirecting to Sourcegraph on success.
  • If you are using an identity provider that supports SAML use the SAML auth provider.
  • If you are using an identity provider that supports OpenID Connect (including Google accounts), use the OpenID Connect provider.
  • If you wish to use LDAP and cannot use the GitHub/GitLab OAuth provider as described above, or if you wish to use another authentication mechanism that is not yet supported, please contact us (we respond promptly).

Most users will use only one auth provider, but you can use multiple auth providers if desired to enable sign-in via multiple services. Identities from different providers will be mapped to a Sourcegraph user by comparing the user’s verified email address to the email address from the external identity provider.

Builtin authentication

The builtin auth provider manages user accounts internally in its own database. It supports user signup, login, and password reset (via email if configured, or else via a site admin).

Site configuration example:

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

The top-level auth.public (default false) site configuration option controls whether anonymous users are allowed to access and use the site without being signed in .

GitHub

Create a GitHub OAuth application (if using GitHub Enterprise, create one on your instance, not GitHub.com). Set the following values, replacing sourcegraph.example.com with the IP or hostname of your Sourcegraph instance:

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

Then add the following lines to your site configuration:

{
  // ...
  "auth.providers": [
    {
      "type": "github",
      "url": "https://github.example.com",  // URL of your GitHub instance; can leave empty for github.com
      "displayName": "GitHub",
      "clientID": "replace-with-the-oauth-client-id",
      "clientSecret": "replace-with-the-oauth-client-secret",
      "allowSignup": false  // Set to true to enable anyone with a GitHub account to sign up without invitation
    }
  ]
}

Replace the clientID and clientSecret values with the values from your GitHub OAuth app configuration.

Leave the url field empty for GitHub.com.

Set allowSignup to true to enable anyone with a GitHub account to sign up without invitation (typically done only for GitHub Enterprise). If allowSignup is false, a user can sign in through GitHub only if an account with the same verified email already exists. If none exists, a site admin must create one explicitly.

GitLab

Create a GitLab OAuth application. Set the following values, replacing sourcegraph.example.com with the IP or hostname of your Sourcegraph instance:

  • Authorization callback URL: https://sourcegraph.example.com/.auth/gitlab/callback
  • Scopes: api, read_user
{
    // ...
    {
      "type": "gitlab",
      "displayName": "GitLab",
      "clientID": "replace-with-the-oauth-application-id",
      "clientSecret": "replace-with-the-oauth-secret",
      "url": "https://gitlab.example.com"
    }

Replace the clientID and clientSecret values with the values from your GitLab OAuth app configuration.

OpenID Connect

The openidconnect auth provider authenticates users via OpenID Connect, which is supported by many external services, including:

To configure Sourcegraph to authenticate users via OpenID Connect:

  1. Create a new OpenID Connect client in the external service (such as one of those listed above).
    • Redirect/callback URI: https://sourcegraph.example.com/.auth/callback (replace https://sourcegraph.example.com with the value of the externalURL property in your config)
  2. Provide the OpenID Connect client’s issuer, client ID, and client secret in the Sourcegraph site configuration shown below.
  3. (Optional) Require users to have a specific email domain name to authenticate (e.g., to limit users to only those from your organization).

Example openidconnect auth provider configuration:

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

Sourcegraph supports the OpenID Connect Discovery standard for configuring the auth provider (using the document at, e.g., https://oidc.example.com/.well-known/openid-configuration).

See the openid auth provider documentation for the full set of configuration options.

G Suite (Google accounts)

Google’s G Suite supports OpenID Connect, which is the best way to enable Sourcegraph authentication using Google accounts. To set it up:

  1. Create an OAuth client ID and client secret in the Google API credentials console. Google’s interactive OpenID Connect documentation page:
    • Application type: Web application
    • Name: Sourcegraph (or any other name your users will recognize)
    • Authorized JavaScript origins: (leave blank)
    • Authorized redirect URIs: https://sourcegraph.example.com/.auth/callback (replace https://sourcegraph.example.com with the value of the externalURL property in your config)
  2. Use the client ID and client secret values in Sourcegraph site configuration (as shown in the example below).
  3. Set your G Suite domain in requireEmailDomain to prevent users outside your organization from signing in.

Example openidconnect auth provider configuration for G Suite:

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

SAML

The saml auth provider authenticates users via SAML 2.0, which is supported by many external services, including:

To configure Sourcegraph to authenticate users via SAML:

  1. Register Sourcegraph as a SAML Service Provider in the external SAML Identity Provider (such as one of those listed above). Use the following settings (the exact names and labels vary across services).
    • Assertion Consumer Service URL, Recipient URL, Destination URL, Single sign-on URL: https://sourcegraph.example.com/.auth/saml/acs (substituting your externalURL)
    • Service Provider (issuer, entity ID, audience URI, metadata URL): https://sourcegraph.example.com/.auth/saml/metadata (substituting your externalURL)
    • Attribute statements:
      • email (required): the user’s email
      • login (optional): the user’s username
      • displayName (optional): the full name of the user
  2. Obtain the SAML identity provider metadata URL and use it in Sourcegraph site configuration as shown below.

Example saml auth provider configuration:

{
  // ...
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "saml",
      // Find this listed in your SAML Identity Provider's admin interface after you've added your SAML app.
      // It's sometimes called the "Identity Provider metadata URL" or "SAML metadata".
      "identityProviderMetadataURL": "https://example.com/saml-metadata"
    }
  ]
}

See the saml auth provider documentation for the full set of configuration options.

SAML troubleshooting

Setting the env var INSECURE_SAML_LOG_TRACES=1 on the sourcegraph/server Docker conatiner (or the sourcegraph-frontend pod if Sourcegraph is deployed to a Kubernetes cluster) causes all SAML requests and responses to be logged.

Vendor-specific SAML instructions

SAML Service Provider metadata

To make it easier to register Sourcegraph as a SAML Service Provider with your SAML Identity Provider, Sourcegraph exposes SAML Service Provider metadata at the URL path /.auth/saml/metadata. For example:

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

HTTP authentication proxies

You can wrap Sourcegraph in an authentication proxy that authenticates the user and passes the user’s username to Sourcegraph via HTTP headers. The most popular such authentication proxy is bitly/oauth2_proxy. Another example is Google Identity-Aware Proxy (IAP). Both work well with Sourcegraph.

To use an authentication proxy to authenticate users to Sourcegraph, add the following lines to your site configuration:

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

Replace X-Forwarded-User with the name of the HTTP header added by the authentication proxy that contains the user’s username.

Ensure that the HTTP proxy is not setting its own Authorization header on the request. Sourcegraph rejects requests with unrecognized Authorization headers and prints the error log lvl=eror msg="Invalid Authorization header." err="unrecognized HTTP Authorization request header scheme (supported values: token, token-sudo)".

For bitly/oauth2_proxy, use the -pass-basic-auth false option to prevent it from sending the Authorization header.

Username header prefixes

Some proxies add a prefix to the username header value. For example, Google IAP sets the x-goog-authenticated-user-id to a value like accounts.google.com:alice rather than just alice. If this is the case, use the stripUsernameHeaderPrefix field. If using Google IAP, for example, add the following lines to your site configuration:

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

Username normalization

Usernames on Sourcegraph are normalized according to the following rules.

  • Any portion of the username after a ‘@’ character is removed
  • Any characters not in [a-zA-Z0-9-] are replaced with -
  • Usernames with consecutive ‘-’ characters are not allowed
  • Usernames that start or end with ‘-’ are not allowed

Usernames from authentication providers are normalized before being used in Sourcegraph. Usernames chosen by users are rejected if they do not meet these criteria.

For example, a user whose external username (according the authentication provider) is [email protected] would have the Sourcegraph username alice-smith.

If multiple accounts normalize into the same username, only the first user account is created. Other users won’t be able to sign in. This is a rare occurrence; contact support if this is a blocker.