Custom SAML Provider

Sentry provides a generic auth provider for SAML2 based authentication, which allows Owners of a Sentry organization to manually configure any SAML2-enabled IdP system. Documented below are the general steps for integration.

Sentry supports the following SAML services:

  • Identity and Service Provider initiated SSO
  • Identity Provider initiated SLO (Single Logout)

Before connecting Sentry to the Identity Provider (IdP), it’s important to first register Sentry as an application on the IdP’s side. Sentry’s SAML endpoints are as follows, where YOUR_ORG_SLUG is substituted for your organization slug:

ACS:

https://sentry.io/saml/acs/YOUR_ORG_SLUG/

SLS:

https://sentry.io/saml/sls/YOUR_ORG_SLUG/

Metadata:

https://sentry.io/saml/metadata/YOUR_ORG_SLUG/

What are these three things?

  • ACS means Assertion Consumer Service. It is used for establishing a session based on rules made between your IdP and the service provider with which it is integrating. Please note that Sentry’s ACS endpoint uses HTTP-POST bindings.
  • SLS stands for Single Logout Service, and is used to address logout requests from the IdP.
  • Metadata, alternatively referred to as the entityID in some systems, refers to the configuration data for an IdP or an SP. In this case, the metadata endpoint in Sentry refers to your Sentry organization’s metadata on the Service Provider end.

When setting these values up on the IdP end, it’s important to remember that Sentry does not need to provide a signing certificate for the integration to work.

There are three distinct methods for registering your IdP with Sentry: Metadata, XML, and data fields. Each method is broken down below, and will produce the same end result.

This method only requires a Metadata URL provided by the IdP platform. After it has been supplied, Sentry will automatically fetch the metadata it needs.

For this method to work, an administrator needs to provide the contents of the IdP’s generated metadata file. Once the contents are pasted directly into the text field, Sentry will do the rest. Please note that Sentry does not require a signing certificate.

Here’s an example of what the Metadata XML contents look like.

Copied
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/SENTRY_APP_ID">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" />
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" />
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

This registration method is the most involved, and requires matching up the data fields from an IdP. The easiest way to accomplish this is to look for the values in a metadata file such as the one provided above.

Based on the XML file example above, the field values to plug in are as follows:

  • EntityID
  • X509Certificate
  • SingleSignOnService

In this example, the SingleLogoutService isn’t provided by the IdP, and is treated as an optional value within Sentry.

Here, the field values of Sentry members need to be matched up with the corresponding values for members in the IdP. The basic required fields are the IdP's User ID and email address, but Sentry can also optionally pull first and last name values from there as well.

Once the SAML integration flow is complete, the related Auth page will reflect the status of a successful integration. From here, you can send reminders to any existing members who existed prior to the integration, and they will receive an email prompt to link their accounts.

Because Sentry uses Just-In-Time (JIT) provisioning, new members are registered with Sentry automatically during their first login attempt with SAML SSO. These accounts will have their membership types delegated based on what the default membership role is in your Organization Settings in Sentry.

SCIM is available for automatic user provisioning, deprovisioning, and team assignment for SAML2 IdPs. Configure Sentry for SCIM, and then follow your IdP's documentation for further setup. Learn more about the Sentry SCIM API endpoints in the SCIM API documentation.

Sentry makes use of Just-In-Time provisioning for member accounts; any new member created within an Identity Provider will have an account automatically created in Sentry when that member attempts to sign into Sentry for the first time.

Existing members will receive an email notifying them of the new SAML authentication option once it is turned on (regardless of enforcement) and they'll be able to link the accounts in the IdP system with their Sentry memberships.

At this time, Sentry's SAML2 integration does not automatically deprovision inactive user accounts. Instead, the member remains inside of Sentry without any means to log in, as they can no longer access the IdP platform for sign-on. For now, inactive member accounts will need to be removed manually by a Manager or an Owner in Sentry.

The crux of the problem here is that different IdP platforms (Okta, Azure AD, etc) use different terms and conventions for the fields necessary for the integration to work. As a result, it’s possible to map up incorrect values into Sentry, causing SSO to fail with this error message.

Help improve this content
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").