Resource Access Management:SAML response for role-based SSO

Background information

In a SAML 2.0-based SSO flow, after an enterprise user signs in to an IdP, the IdP generates an authentication response containing a SAML assertion per the SAML 2.0 HTTP-POST binding. The browser or application automatically forwards this response to Alibaba Cloud, which uses the assertion to verify the user's sign-in status and extract the sign-in subject. The assertion must include all elements required by Alibaba Cloud, or SSO fails.

SAML response

Your IdP must send a SAML response to Alibaba Cloud with all mandatory elements listed below. If any element is missing, 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:AttributeStatement>
            <saml2:Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName">
                ...
            </saml2:Attribute>
            <saml2:Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/Role">
                ...
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

SAML assertion elements

• Standard SAML 2.0 elements

  These elements follow the SAML 2.0 protocol specification.

  Element	Description
  Issuer	The value of Issuer must match the EntityID in the IdP metadata file that you uploaded when you created the IdP entity in Alibaba Cloud.
  Signature	Alibaba Cloud requires a signed SAML assertion to prevent tampering. The Signature element and its child elements must contain information such as the signature value and signing algorithm.
  Subject	The Subject element must contain the following elements: Exactly one NameID element. Set the NameID value per the SAML 2.0 protocol, typically to the user's IdP identifier. Alibaba Cloud does not use this value to identify the sign-in subject. Exactly one SubjectConfirmation element containing a SubjectConfirmationData element. The SubjectConfirmationData element requires these attributes: NotOnOrAfter: Specifies the expiration time of the SAML assertion. Recipient: Alibaba Cloud checks the value of this attribute to verify that the assertion is intended for Alibaba Cloud. The value must be https://signin.alibabacloud.com/saml-role/sso. Example Subject element: <Subject> <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">administrator</NameID> <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData NotOnOrAfter="2019-01-01T00:01:00.000Z" Recipient="https://signin.alibabacloud.com/saml-role/sso"/> </SubjectConfirmation> </Subject>
  Conditions	The Conditions element must include an AudienceRestriction element with at least one Audience element. One Audience element must have the value urn:alibaba:cloudcomputing:international. Note If you configure multiple SAML applications in your IdP that point to Alibaba Cloud RAM and use Entity IDs with parameters (for example, urn:alibaba:cloudcomputing:international#abc.123), the Audience element must exactly match the Entity ID, including the parameter suffix. Example Conditions element: <Conditions> <AudienceRestriction> <Audience>urn:alibaba:cloudcomputing:international</Audience> </AudienceRestriction> </Conditions>

• Alibaba Cloud custom elements

  The AttributeStatement element must include the following Alibaba Cloud-specific Attribute elements:

  • An Attribute element whose Name attribute is https://www.aliyun.com/SAML-Role/Attributes/Role

    This element is required and supports multiple values. Each AttributeValue specifies a role the user can assume, formatted as the RAM role ARN and IdP ARN separated by a comma (,). Obtain both ARNs from the console:

    • RAM role ARN: On the Roles page, click the RAM role name, and then find the ARN in the Basic Information section.

    • IdP ARN: On the SSO page, on the Role-based SSO tab, click the IdP name, and then find the ARN in the Details section.

    Note

    If multiple values are provided, users signing in to the console can select a role from the displayed list.

    Example Role Attribute element:

    <Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/Role">      
      <AttributeValue>acs:ram::$account_id:role/role1,acs:ram::$account_id:saml-provider/provider1</AttributeValue>
      <AttributeValue>acs:ram::$account_id:role/role2,acs:ram::$account_id:saml-provider/provider1</AttributeValue>
    </Attribute>               

    Note

    $account_id is the ID of the Alibaba Cloud account that owns the RAM roles and IdP.

  • An Attribute element whose Name attribute is https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName

    This element is required and accepts only one value. The AttributeValue appears in the console user information and ActionTrail logs. Use a unique RoleSessionName per user (such as employee ID or email) to distinguish users who assume the same role.

    The AttributeValue must be 2 to 64 characters and can contain letters, digits, and the following special characters: -_.@=.

    Example RoleSessionName Attribute element:

    <Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName">
      <AttributeValue>user_id</AttributeValue>
    </Attribute>                     

  • An Attribute element whose Name attribute is https://www.aliyun.com/SAML-Role/Attributes/SessionDuration

    This element is optional and accepts at most one value. The AttributeValue must be an integer representing the session duration in seconds. The minimum is 900, and the maximum cannot exceed the maximum session duration configured for the RAM role specified in the Role attribute.

    Example SessionDuration Attribute element:

    <Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/SessionDuration">
      <AttributeValue>1800</AttributeValue>
    </Attribute>                  

• Session duration

  For console sign-in, the SessionDuration value from the SAML assertion is used as the session duration. If the AuthnStatement element also defines SessionNotOnOrAfter, the shorter of SessionDuration and SessionNotOnOrAfter applies. If neither is specified, the session duration defaults to the Maximum Session Duration setting for the role, capped by the Login session duration setting. Manage RAM user security settings. Set the maximum session duration for a RAM role.

  For programmatic sign-in, if you specify DurationSeconds when calling AssumeRoleWithSAML and also define SessionNotOnOrAfter in the AuthnStatement element, the STS token validity is the shorter of DurationSeconds and SessionNotOnOrAfter. If neither is specified, the validity defaults to 3,600 seconds.

Related documents

How do I view a SAML response in a browser?