SAML Response Requirements

2025-08-26 02:19

When performing SAML SSO login, the SAML response must contain specific elements, especially those within the SAML assertion, to ensure successful SSO login.

Background

In the SSO process based on SAML 2.0, when enterprise users log in to the IdP (Identity Provider), the IdP will generate an authentication response containing the SAML assertion according to the requirements of SAML 2.0 HTTP-POST binding. This response will be automatically forwarded to ZOLOZ via the browser or application. ZOLOZ uses the SAML assertion to confirm the user's login status and extract the login subject from it. Therefore, the SAML assertion must contain all elements required by ZOLOZ; otherwise, it will not be able to verify the identity of the logged-in user, leading to SSO login failure.

Please refer to the XML instructions in the SAML Core standard of the SAML 2.0 protocol to ensure that the SAML response is encoded using the standard XML format.

SAML Response Requirements

Please ensure that your IdP issues a SAML response to ZOLOZ that meets the following requirements. Each element in the response must be included; otherwise, it may result in SSO login failure.

copy
<saml2p:Response
  InResponseTo="...">
  <saml2:Issuer>...</saml2:Issuer>
  <saml2p:Status>
    ...
  </saml2p:Status>
  <saml2:Assertion>
    <saml2:Issuer>...</saml2:Issuer>
    <ds:Signature>
      <ds:SignatureValue>...</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml2:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress">...</saml:NameID>
    </saml2:Subject>
    <saml2:Conditions
      NotBefore="..."
    NotOnOrAfter="...">      
    </saml2:Conditions>
  </saml2:Assertion>
</saml2p:Response>

Elements Description within the SAML Assertion

Common Elements of the SAML 2.0 Protocol

For more information on the SAML 2.0 protocol, please refer to SAML 2.0.

Element	Description
Signature	ZOLOZ requires the SAML assertion to be signed to ensure it has not been tampered with. The Signature and its elements must include the signature value, signature algorithm, and certificate (the `<X509Certificate>` tag), among other information.
Response	The `Response` tag must include the InResponseTo value, which is used to verify whether the request was initiated by ZOLOZ.
Subject	The `Subject` element must include one `NameID` element with the emailAddress format, which is the identity identifier for the ZOLOZ Portal account.
Conditions	The `Conditions` element must include `NotOnOrAfter` and `NotBefore` elements, which stipulate the validity period of the SAML assertion.

NameID Element

ZOLOZ Portal SSO locates the corresponding sub-account through the user's email (the email provided when creating the sub-account). Therefore, the SAML assertion generated by the enterprise IdP must include the user's email. ZOLOZ Portal matches the sub-account's user email by parsing elements within the SAML assertion.

When configuring the SAML assertion issued by the IdP, the user email field for the corresponding sub-account must be mapped to the NameID element in the SAML assertion. Depending on the specific implementation of the IdP, you can choose the field to map, such as UPN, email, etc.