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
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:
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.
Note
Once you enable SSO, this will be the only way to login to your self-hosted instance. If you need free registration along with SSO, you can comment on the GitHub PR for this.
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:
auth-google.client-id: "<client id>"
auth-google.client-secret: "<client secret>"
Note
After changing configuration files, re-run the ./install.sh script, to rebuild and restart the containers. See the configuration section for more information.
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.
The GitHub App name must not contain any spaces.
If the form above does not work for you, you need the following settings for your GitHub Application:
| Setting | Value |
|---|---|
| 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" |
Don't forget to replace all occurances of ${urlPrefix} with your own url prefix.
When prompted for permissions, choose the following:
| Permission | Setting |
|---|---|
| Organization permissions / members | Read-only |
| User permissions / Email addresses | Read-only |
| Repository administration | Read-only |
| Repository contents | Read-only |
| Issues | Read & write |
| Pull requests | Read & write |
| Repository webhooks | Read & write |
You will then need to set the following configuration values:
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"
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.
Note
After changing configuration files, re-run the ./install.sh script, to rebuild and restart the containers. See the configuration section for more information.
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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").