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
.
Value | Other names | Description Example |
---|---|---|
SP Entity ID | SP URL, audience restriction | The UUID for this SAML identity provider |
SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL 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) URL | URL where IdP begins SSO | GET https://api.zoo.dev/auth/saml/providers/{entity_id}/login , where the Entity ID is the same as above |
SP Single Log-Out (SLO) URL | URL where a user is logged out | GET 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.
Name | Required | Description |
---|---|---|
NameID | ✔ | A persistent user identifier. Any persistent name identifier format may be used. |
email | ✔ | The email address for the user. |
first_name | ✔ | The first name of the user. |
last_name | ✔ | The last name of the user. |
SessionNotOnOrAfter | ✘ | The 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.