Stytch allows your organizations to use SAML SSO as an authentication method. Stytch will act as the Service Provider (SP) in front of your organizations, and interface with the Identity Provider (IdP), which will provide authentication assertions.

Attribute mappings:

Stytch requires any identity provider to specify the email and name of the member attempting to log in. It parses these from the attributes sent in the IdP's assertion to Stytch. To recognize which attributes correspond to which fields, Stytch allows your connection to define an attribute_mapping.

An example attribute_mapping looks like this:

{
  "email": "EmailAddress",
  "full_name": "FullName",
  "idp_user_id": "ExternalID",
  "title": "Title",
}

Stytch requires an email key to be present to determine the member's email. If the connection uses the Email Address NameID format, set the email key to NameID to tell Stytch to parse the email from the NameID. If the connection uses an alternative NameID format, set email to the value of the SAML attribute containing the member's email. Additionally, in order to determine the member's name, Stytch requires either the full_name key to be present, or both the first_name and last_name keys. We strongly recommend configuring an idp_user_id attribute, set to the user's stable ID in their IdP. This will allow Stytch to find the existing Member in the event of an IdP-driven email change, and log the user into their existing account rather than creating a new Member record.

Stytch reserves the following Attribute Mapping keys for internal use:

• email
• full_name
• first_name
• last_name
• groups
• idp_user_id Any additional Custom Attribute Mappings defined will be used to promote SSO Attributes to the member's Trusted Metadata. Custom SSO Attributes will be merged with the member's existing Trusted Metadata using Stytch's metadata update behavior.

Some considerations for using SSO Custom Attributes:

• Although Trusted Metadata can still be updated directly via the Update Member endpoint, fields driven by the IDP will be overwritten again on subsequent logins.
• Metadata derived from IDP attributes will still exist after the IDP is deleted.
• If an IDP does NOT send a field, or the field is removed from the attribute mapping, Stytch will NOT delete the field from the Trusted Metadata on next login. All fields need to be deleted explicitly via the Update Member endpoint.

Putting this all together, given the following SAML assertion:

<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Attribute Name="EmailAddress"
                     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">john.doe@example.com
        </saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="FullName"
                     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">John Doe
        </saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="ExternalID"
                     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">u_123_example
        </saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="Title"
                     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Staff Software Engineer
        </saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>

Stytch will extract the following values:

• member.email: john.doe@example.com
• member.full_name: John Doe
• member.sso_registrations[0].external_id: u_123_example
• member.trusted_metadata.title: Staff Software Engineer

The attribute mapping can be set in the Update SAML Connection endpoint.

Single sign-on URLs:

Some IdPs may ask for a single sign-on URL. This is listed as the acs_url in the SAML connection object. Note that for Stytch's purposes, the acs_url and audience_uri are the same value.