Sourcegraph can be configured to enforce repository permissions from code hosts.
Currently, GitHub, GitHub Enterprise, GitLab and Bitbucket Server permissions are supported. Check our product direction for plans to support other code hosts. If your desired code host is not yet on the roadmap, please open a feature request.
Prerequisite: Add GitHub as an authentication provider.
Then, add or edit a GitHub external service and include the authorization
field:
{ "url": "https://github.com", "token": "$PERSONAL_ACCESS_TOKEN", "authorization": { "ttl": "3h" } }
GitLab permissions can be configured in three ways:
http-header
authentication).Prerequisite: Add GitLab as an authentication provider.
Then, add or edit a GitLab external service and include the authorization
field:
{ "url": "https://gitlab.com", "token": "$PERSONAL_ACCESS_TOKEN", "authorization": { "identityProvider": { "type": "oauth" }, "ttl": "3h" } }
Prerequisite: Add the SAML or OpenID Connect authentication provider you use to sign into GitLab.
Then, add or edit a GitLab external service and include the authorization
field:
{ "url": "https://gitlab.com", "token": "$PERSONAL_ACCESS_TOKEN", "authorization": { "identityProvider": { "type": "external", "authProviderID": "$AUTH_PROVIDER_ID", "authProviderType": "$AUTH_PROVIDER_TYPE", "gitlabProvider": "$AUTH_PROVIDER_GITLAB_ID" }, "ttl": "3h" } }
$AUTH_PROVIDER_ID
and $AUTH_PROVIDER_TYPE
identify the authentication provider to use and should
match the fields specified in the authentication provider config
(auth.providers
). $AUTH_PROVIDER_GITLAB_ID
should match the identities.provider
returned by
the admin GitLab Users API endpoint.
Prerequisite: Ensure that http-header
is the only authentication provider type configured for
Sourcegraph. If this is not the case, then it will be possible for users to escalate privileges,
because Sourcegraph usernames are mutable.
Add or edit a GitLab external service and include the authorization
field:
{ "url": "https://gitlab.com", "token": "$PERSONAL_ACCESS_TOKEN", "authorization": { "identityProvider": { "type": "username" }, "ttl": "3h" } }
Enforcing Bitbucket Server permissions can be configured via the authorization
setting in its external service configuration.
auth.enableUsernameChanges
to false
in the Critical site config to prevent users from changing their usernames and escalating their privileges.This section walks you through the process of setting up an Application Link between Sourcegraph and Bitbucket Server and configuring the Bitbucket Server external service with authorization
settings. It assumes the above prerequisites are met.
As an admin user, go to the "Application Links" page. You can use the sidebar navigation in the admin dashboard, or go directly to https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks.
Write Sourcegraph's external URL in the text area (e.g. https://sourcegraph.example.com
) and click Create new link. Click Continue even if Bitbucket Server warns you about the given URL not responding.
Write Sourcegraph
as the Application Name and select Generic Application
as the Application Type. Leave everything else unset and click Continue.
Now click the edit button in the Sourcegraph
Application Link that you just created and select the Incoming Authentication
panel.
Generate a Consumer Key in your terminal with echo sourcegraph$(openssl rand -hex 16)
. Copy this command's output and paste it in the Consumer Key field. Write Sourcegraph
in the Consumer Name field.
Generate an RSA key pair in your terminal with openssl genrsa -out sourcegraph.pem 4096 && openssl rsa -in sourcegraph.pem -pubout > sourcegraph.pub
. Copy the contents of sourcegraph.pub
and paste them in the Public Key field.
Scroll to the bottom and check the Allow 2-Legged OAuth checkbox, then write your admin account's username in the Execute as field and, lastly, check the Allow user impersonation through 2-Legged OAuth checkbox. Press Save.
Go to your Sourcegraph's external services page (i.e. https://sourcegraph.example.com/site-admin/external-services
) and either edit or create a new Bitbucket Server external service. Click on the Enforce permissions quick action on top of the configuration editor. Copy the Consumer Key you generated before to the oauth.consumerKey
field and the output of the command base64 sourcegraph.pem | tr -d '\n'
to the oauth.signingKey
field.
Permissions for each user are cached for the configured ttl
duration (3h by default). When the ttl
expires for a given user, during request that needs to be authorized, permissions will be refetched from Bitbucket Server again in the background, during which time the previously cached permissions will be used to authorize the user's actions. A lower ttl
makes Sourcegraph refresh permissions for each user more often which increases load on Bitbucket Server, so have that in consideration when changing this value.
The default hardTTL
is 3 days, after which a user's cached permissions must be updated before any user action can be authorized. While the update is happening an error is returned to the user. The default hardTTL
value was chosen so that it reduces the chances of users being forced to wait for their permissions to be updated after a weekend of inactivity.
Finally, save the configuration. You're done!