--- title: "Single Sign-On (SSO)" url: https://develop.sentry.dev/self-hosted/configuration/sso/ --- # 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)](https://develop.sentry.dev/self-hosted/configuration/sso.md#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`](https://github.com/getsentry/self-hosted/blob/10.0.1/sentry/requirements.example.txt) before running `./install.sh`: ```bash 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](https://sentry.io) except, you need to use your own instance's [`url-prefix`](https://develop.sentry.dev/config.md#general) for the URLs mentioned in the documentation. Please refer to our [main SAML documentation](https://docs.sentry.io/accounts/sso/#saml2-identity-provider) for all the details. ## [SSO with OAuth](https://develop.sentry.dev/self-hosted/configuration/sso.md#sso-with-oauth) ##### 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](https://github.com/getsentry/sentry/pull/16247) for this. ### [Google Auth](https://develop.sentry.dev/self-hosted/configuration/sso.md#google-auth) As of [Sentry 9.1](https://github.com/getsentry/self-hosted/releases/tag/9.1.2), 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](https://developers.google.com/identity/sign-in/web/server-side-flow#step_1_create_a_client_id_and_client_secret) and then enter these values into your [`sentry/config.yaml`](https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml) file respectively: ```yaml auth-google.client-id: "" auth-google.client-secret: "" ``` ##### Note After changing configuration files, re-run the `./install.sh` script, to rebuild and restart the containers. See the [configuration section](https://develop.sentry.dev/self-hosted.md#configuration) for more information. ### [GitHub Auth](https://develop.sentry.dev/self-hosted/configuration/sso.md#github-auth) As of [Sentry 10](https://github.com/getsentry/self-hosted/releases/tag/10.0.1), 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](https://develop.sentry.dev/self-hosted/configuration/sso.md#create-github-app-for-sso--integration) The GitHub App name must not contain any spaces. Account Type \[x]Organization\[ ]Personal GitHub Org Slug your-organization Sentry `url-prefix` https\://your-sentry-url-prefix.com 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 occurrences 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 | #### [Update your configuration with your GitHub App information](https://develop.sentry.dev/self-hosted/configuration/sso.md#update-your-configuration-with-your-github-app-information) You will then need to set the following configuration values: In [`sentry/config.yaml`](https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml) ```yaml github-app.id: github-app.name: "" github-app.webhook-secret: "" # Use only if configured in GitHub github-app.client-id: "" github-app.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: "" github-login.client-secret: "" github-login.require-verified-email: true # Optional but recommended ``` This will also enable the [GitHub Integration](https://develop.sentry.dev/integrations/github.md) for your instance. ##### Note After changing configuration files, re-run the `./install.sh` script, to rebuild and restart the containers. See the [configuration section](https://develop.sentry.dev/self-hosted.md#configuration) for more information. ### [Custom Providers](https://develop.sentry.dev/self-hosted/configuration/sso.md#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](https://github.com/getsentry/sentry/tree/master/src/sentry/auth/providers).