# 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://docs.sentry.io/.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/.md) 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.md#saml2-identity-provider) for all the details.

## [SSO with OAuth](https://docs.sentry.io/.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.md) for this.

### [Google Auth](https://docs.sentry.io/.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.md#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: "<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](https://docs.sentry.io/self-hosted.md#configuration) for more information.

### [GitHub Auth](https://docs.sentry.io/.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://docs.sentry.io/.md#create-github-app-for-sso--integration)

The GitHub App name must not contain any spaces.

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 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 |

#### [Update your configuration with your GitHub App information](https://docs.sentry.io/.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: <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>"
github-login.require-verified-email: true # Optional but recommended
```

This will also enable the [GitHub Integration](https://docs.sentry.io/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://docs.sentry.io/self-hosted.md#configuration) for more information.

### [Custom Providers](https://docs.sentry.io/.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.md).
