Sign In

Self-Hosted Single Sign-On (SSO)

SSO in Sentry is handled in one of two ways:

  • Via a middleware which handles an upstream proxy dictating the authenticated user
  • Via a third-party service which implements an authentication pipeline

Using a middleware proxy (SAML2)

As of Sentry 20.6.0, self-hosted Sentry comes with built-in support for SAML2 and certain auth providers. For older versions you will need to add the following line into sentry/requirements.txt before running ./install.sh:

Copied
sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2

The way you can set this up is the same as sentry.io except, you need to use your own instance's url-prefix for the URLs mentioned in the documentation.

Please refer to our main SAML documentation for all the details.

SSO with OAuth

Google Auth

As of Sentry 9.1, self-hosted Sentry comes with built-in Google Auth support. To enable, you'll need to create a client ID and secret for your Google App and then enter these values into your sentry/config.yaml file respectively:

Copied
auth-google.client-id: '<client id>'
auth-google.client-secret: '<client secret>'

GitHub Auth

As of Sentry 10, self-hosted Sentry comes with built-in GitHub Auth support. To enable, you'll need to create a new GitHub App under your organization and install it.

Create GitHub App for SSO & integration

If the form above does not work for you, you need the following settings for your GitHub Application:

SettingValue
Homepage URL${url-prefix}
Callback URLs${url-prefix}/auth/sso/ and ${url-prefix}/extensions/github/setup/
Setup URL (optional)${url-prefix}/extensions/github/setup/
Webhook URL${url-prefix}/extensions/github/webhook/
Webhook secret"my-super-secret-example-secret"

When prompted for permissions, choose the following:

PermissionSetting
Organization permissions / membersRead-only
User permissions / Email addressesRead-only
Repository administrationRead-only
Repository contentsRead-only
IssuesRead & write
Pull requestsRead & write
Repository webhooksRead & write

Update your configuration with your GitHub App information

You will then need to set the following configuration values:

In sentry/sentry.conf.py

Copied
GITHUB_APP_ID="<App ID>"
GITHUB_API_SECRET="<Client secret>"
GITHUB_REQUIRE_VERIFIED_EMAIL = True  # Optional but recommended

# Only if you are using GitHub Enterprise
#GITHUB_BASE_DOMAIN = "git.example.com"
#GITHUB_API_DOMAIN = "api.git.example.com"

In sentry/config.yaml

Copied
github-app.id: <App ID>
github-app.name: '<GitHub App name>'
github-app.webhook-secret: '<Webhook secret>' # Use only if configured in GitHub
github-app.client-id: '<Client ID>'
github-app.client-secret: '<Client secret>'
github-app.private-key: |
  -----BEGIN RSA PRIVATE KEY-----
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  -----END RSA PRIVATE KEY-----

# Only needed if you have multiple organizations enabled
github-login.client-id: '<Client ID>'
github-login.client-secret: '<Client secret>'

This will also enable the GitHub Integration for your instance.

Custom Providers

At this time the API is considered unstable and subject to change. Things likely won’t change a lot, but there’s a few areas that need some cleaning up.

With that in mind, if you wish to build your own, take a look at one of the reference implementations above.

You can edit this page on GitHub.