Sourcegraph supports the following ways for users to sign in:
The authentication provider is configured in the auth.providers
site configuration option.
If you are unsure which auth provider is right for you, we recommend applying the following rules in order:
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.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.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.
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 }] }
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:
https://sourcegraph.example.com
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 "allowOrgs": ["your-org-name"] // Restrict logins to members of these orgs. } ] }
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.
The allowOrgs
fields restricts logins to members of the specified GitHub organizations. Existing user sessions are not invalidated. Only new logins after this setting is changed are affected.
Once you've configured GitHub as a sign-on provider, you may also want to add GitHub repositories to Sourcegraph.
Create a GitLab OAuth application. Set
the following values, replacing sourcegraph.example.com
with the IP or hostname of your
Sourcegraph instance:
https://sourcegraph.example.com/.auth/gitlab/callback
api
, read_user
Then add the following lines to your 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" } ]
Replace the clientID
and clientSecret
values with the values from your GitLab OAuth app
configuration.
Once you've configured GitLab as a sign-on provider, you may also want to add GitLab repositories to Sourcegraph.
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:
https://sourcegraph.example.com/.auth/callback
(replace https://sourcegraph.example.com
with the value of the externalURL
property in your config)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.
Google's G Suite supports OpenID Connect, which is the best way to enable Sourcegraph authentication using Google accounts. To set it up:
https://sourcegraph.example.com/.auth/callback
(replace https://sourcegraph.example.com
with the value of the externalURL
property in your config)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" } ] }
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 pusher/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 pusher/oauth2_proxy, use the -pass-basic-auth false
option to prevent it from sending the Authorization
header.
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-email", "stripUsernameHeaderPrefix": "accounts.google.com:" } ] }
Usernames on Sourcegraph are normalized according to the following rules.
[a-zA-Z0-9-.]
are replaced with -
@
character are interpreted as an email address, so the username will be extracted by truncating at the @
character.@
characters are not considered an email address, so the @
will be treated as a non-standard character and be replaced with -
-
or .
characters are not allowed.
are not allowed-
are not allowedUsernames 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.