SAML configuration reference

About SAML configuration

To use SAML single sign-on (SSO) for authentication to Zoo, you must configure both your external SAML identity provider (IdP) and your enterprise or organization on zoo.dev. In a SAML configuration, Zoo functions as a SAML service provider (SP).

Zoo provides integration according to the SAML 2.0 specification. For more information, see the SAML Wiki on the OASIS website.

You must enter unique values from your SAML IdP when configuring SAML SSO for Zoo, and you must also enter unique values from Zoo on your IdP.

SAML metadata

The SP metadata for Zoo is available for either organizations or enterprises with SAML SSO. Zoo uses the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST binding.

Organizations

You can configure SAML SSO for an individual organization.

The SP metadata for an organization on zoo.dev is available at /org/saml/idp.

ValueOther namesDescription Example
SP Entity IDSP URL, audience restrictionThe UUID for this SAML identity provider
SP Assertion Consumer Service (ACS) URLReply, recipient, or destination URLURL where IdP sends SAML responses POST https://api.zoo.dev/auth/saml/providers/{entity_id}/login, where the Entity ID is the same as above
SP Single Sign-On (SSO) URLURL where IdP begins SSOGET https://api.zoo.dev/auth/saml/providers/{entity_id}/login, where the Entity ID is the same as above
SP Single Log-Out (SLO) URLURL where a user is logged outGET https://api.zoo.dev/logout. This will expire the current session for the authenticated user.

When you enter your email into https://zoo.dev/signin it will automatically redirect you to the SP Single Sign-On URL as denoted above. This way you do not need to remember it every time you login.

SAML attributes

The following SAML attributes are available for Zoo.

NameRequiredDescription
NameIDA persistent user identifier. Any persistent name identifier format may be used.
emailThe email address for the user.
first_nameThe first name of the user.
last_nameThe last name of the user.
SessionNotOnOrAfterThe date that Zoo invalidates the associated session. After invalidation, the person must authenticate once again to access your enterprise's resources.

Note: It's important to use a human-readable, persistent identifier for NameID. Using a transient identifier format like urn:oasis:names:tc:SAML:2.0:nameid-format:transient will result in re-linking of accounts on every sign-in, which can be detrimental to authorization management.

SAML response requirements

Zoo requires that the response message from your IdP fulfill the following requirements.

  • Your IdP must protect each assertion in the response with a digital signature. You can accomplish this by signing each individual <Assertion> element or by signing the <Response> element.

  • Your IdP must provide a <NameID> element as part of the <Subject> element. You may use any persistent name identifier format.

  • Your IdP must include the Recipient attribute, which must be set to the ACS URL. The following example demonstrates the attribute.

    <samlp:Response ...>
    <saml:Assertion ...>
        <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
            <saml:SubjectConfirmationData Recipient="https://api.zoo.dev/auth/saml/providers/{entity_id}/login" .../>
        </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:AttributeStatement>
        <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
            <saml:AttributeValue>monalisa</saml:AttributeValue>
        </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
    </samlp:Response>
    

Session duration and timeout

To prevent a person from authenticating with your IdP and staying authorized indefinitely, Zoo periodically invalidates the session for each user account with access to your enterprise's resources. After invalidation, the person must authenticate with your IdP once again.

By default, if your IdP does not assert a value for the SessionNotOnOrAfter attribute, Zoo invalidates a session 24 hours after successful authentication with your IdP.

Zoo will support a customized session duration if your IdP provides the option to configure a SessionNotOnOrAfter attribute and value.

If you define a customized session duration value less than 24 hours, Zoo may prompt people to authenticate every time Zoo initiates a redirect.

To prevent authentication errors, we recommend a minimum session duration of 4 hours.

Notes:

  • For Azure AD, the configurable lifetime policy for SAML tokens does not control session timeout for Zoo.
  • Okta does not currently send the SessionNotOnOrAfter attribute during SAML authentication with Zoo. For more information, contact Okta.