This topic describes the syntax of a SAML response for user-based single sign-on (SSO). This topic also describes the elements of a SAML assertion in a SAML response.

Background information

During SAML 2.0-based SSO, after the identity of a user is verified, your identity provider (IdP) generates an authentication response and sends it to Alibaba Cloud by using a browser or a program. This response contains a SAML assertion that complies with the specifications of HTTP post binding in SAML 2.0. Alibaba Cloud uses the SAML assertion to determine the logon status and identity of the user. Therefore, the SAML assertion must contain the elements that are required by Alibaba Cloud. If the SAML assertion does not contain the required elements, SSO fails.

SAML response

Make sure that each SAML response that is sent by your IdP to Alibaba Cloud includes the following elements. Otherwise, SSO fails.

<saml2p:Response>
    <saml2:Issuer>...</saml2:Issuer>
    <saml2p:Status>
        ...
    </saml2p:Status>
    <saml2:Assertion>
        <saml2:Issuer>...</saml2:Issuer>
        <ds:Signature>
            ...
        </ds:Signature>
        <saml2:Subject>
            <saml2:NameID>${NameID}</saml2:NameID>
            <saml2:SubjectConfirmation>
                ...
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions>
            <saml2:AudienceRestriction>
                <saml2:Audience>${Audience}</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement>
            ...
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

Elements in a SAML assertion

  • Common elements in SAML 2.0
    Element Description
    Issuer The value of the Issuer element must match the EntityID in the metadata file that you have uploaded for the IdP in the Alibaba Cloud Management Console.
    Signature The SAML assertion must be signed. The Signature element must contain information such as the signature value and signature algorithm. The signature is used to ensure that the signed SAML assertion is not tampered with.
    Subject

    The Subject element must contain the following sub-elements:

    • Only one NameID sub-element. It is used to identify a RAM user under your Alibaba Cloud account. For more information, see the description and example of NameID in this topic.
    • Only one SubjectConfirmation sub-element that contains a SubjectConfirmationData sub-element. The SubjectConfirmationData sub-element must contain the following attributes:
      • NotOnOrAfter: specifies the validity period of a SAML assertion.
      • Recipient: Alibaba Cloud checks whether it is the recipient of the SAML assertion based on the value of this attribute. Therefore, you must set this attribute tohttps://signin-intl.aliyun.com/${accountId}/saml/SSO. ${accountId} specifies the ID of the Alibaba Cloud account.

      The following script provides an example of the Subject element:

      <Subject>
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">Alice@example.onaliyun.com</NameID>        
        <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">   
          <SubjectConfirmationData NotOnOrAfter="2019-01-01T00:01:00.000Z" Recipient="https://signin-intl.aliyun.com/${accountId}/saml/SSO"/>    
        </SubjectConfirmation>
      </Subject>
    Conditions

    The Conditions element must contain an AudienceRestriction sub-element. The AudienceRestriction sub-element can contain one or more Audience sub-elements. The value of an Audience sub-element must be https://signin-intl.aliyun.com/${accountId}/saml/SSO. ${accountId} specifies the ID of the Alibaba Cloud account.

    The following script provides an example of the Conditions element:

    <Conditions>
      <AudienceRestriction>
        <Audience>https://signin-intl.aliyun.com/${accountId}/saml/SSO</Audience>
      </AudienceRestriction>
    </Conditions>           
  • NameID element

    Alibaba Cloud uses a User Principal Name (UPN) to locate a RAM user. Therefore, the SAML assertion that is generated by your IdP must contain the UPN of the RAM user. To implement user-based SSO, Alibaba Cloud resolves the NameID element in the SAML assertion and maps this element to the UPN of the corresponding RAM user.

    When you configure the SAML assertion that is issued by your IdP, you must map the UPN of the RAM user to the NameID element in the SAML assertion.

    The value of the NameID element must include one of the following suffixes:

    • The domain alias of your Alibaba Cloud account: <username>@<domain_alias>. <username> specifies the username of a RAM user. <domain_alias> specifies the domain alias. For more information, see Create and verify a domain alias.
    • The auxiliary domain name: <username>@<auxiliary_domain>. <username> specifies the username of the RAM user. <auxiliary_domain> specifies the auxiliary domain name. For information about how to configure an auxiliary domain name, see Configure the SAML settings of Alibaba Cloud for user-based SSO.
      Note If you configure both a domain alias and an auxiliary domain name, the value of the NameID element is suffixed with the domain alias.
    • The default domain name of your Alibaba Cloud account: <username>@<default_domain>. <username> specifies the username of a RAM user. <default_domain> specifies the default domain name. For more information, see Manage the default domain name.
      Note You can use the default domain name of your Alibaba Cloud account as the suffix of the NameID element even if you have configured a domain alias or an auxiliary domain name.
  • NameID example

    In this example, a RAM user who is named Alice is created for your Alibaba Cloud account and the default domain name of your Alibaba Cloud account is example.onaliyun.com.

    • If you have set the domain alias of your Alibaba Cloud account to example.com, the value of the NameID element in a SAML assertion is Alice@example.onaliyun.com or Alice@example.com.
    • If you have set the auxiliary domain name to example2.com and no domain alias is configured, the value of the NameID element in a SAML assertion is Alice@example.onaliyun.com or Alice@example2.com.
    • If you have set the domain alias of your Alibaba Cloud account to example.com and the auxiliary domain name to example2.com, the value of the NameID element in a SAML assertion is Alice@example.onaliyun.com or Alice@example.com. The auxiliary domain name cannot be used.