This article reviews how to configure SAML authentication, which allows you to authenticate Stoplight users using a company SSO provider.

Before continuing, be sure to:

• Contact the team responsible for your organization's SAML configuration for the following pieces of information that must be configured within Stoplight:
  • SAML Entry Point URL - This is the URL where applications integrating with a SAML IdP must first direct users
  • SAML Identifier Format - Stoplight defaults to using a "persistent" name identifier format, however some SAML providers require a specific format ("unspecified", for example)
• Some fields will also need to be configured within the SAML IdP directly. Pass along the following pieces of information to the team responsible for your organization's SAML configuration:
  • Issuer - This value defaults to "stoplight"
  • Callback URL - This value is provided during the configuration, and defaults to a value similar to "https://your-stoplight-server.example.com/oauth/callback"
  • Attributes - The attributes described below are required by Stoplight to successfully authenticate users.
• Be logged in to Stoplight as an Administrator

SAML Assertion Requirements 

In addition to the items above, the following SAML attributes need to be provided in the assertion data coming to Stoplight upon successful authentication with the SAML IdP:

• External ID - This corresponds to the "nameID" field in the SAML response
• Username - This corresponds to one of the following fields in the SAML response (in order of precedence):
  • userName
  • urn:oid:2.5.4.42
  • displayName
  • urn:oid:2.5.4.4
• Email - this corresponds to either the "email" or "urn:oid:1.2.840.113549.1.9.1" attributes

From the Stoplight Landing Screen

From the Admin Settings

From the External Services Screen

Registering the SAML Service