SAML response for role-based SSO - SSO Management| Alibaba Cloud Documentation Center

Background information

During SAML 2.0-based SSO, after the identity of a user is verified, your 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

This section describes the syntax of a SAML response. Make sure that each SAM response sent by your IdP to Alibaba Cloud includes the following elements. Otherwise, SSO may fail.

<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>

Elements in a SAML assertion

Common elements in SAML 2.0


Element	Description
`Issuer`	The value of the `Issuer` element must match `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 confirm that the signed SAML assertion has not been modified since the signature was generated.
`Subject`	The `Subject` element must contain the following sub-elements: Only one `NameID` sub-element. You must specify the value of `NameID` based on SAML 2.0. However, Alibaba Cloud does not determine a logon identity based on the value of `NameID`. 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 the 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 the attribute to `https://signin.alibabacloud.com/saml-role/sso`. The following script provides an example of the `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 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 `urn:alibaba:cloudcomputing:international`. The following script provides an example of the `Conditions` element: `<Conditions> <AudienceRestriction> <Audience>urn:alibaba:cloudcomputing:international</Audience> </AudienceRestriction> </Conditions>`

Custom elements required by Alibaba Cloud
The AttributeStatement element in a SAML assertion must contain the following Attribute sub-elements that are required by Alibaba Cloud:
- Role attribute: an Attribute element with the Name attribute set to https://www.aliyun.com/SAML-Role/Attributes/Role
  Required. This element contains one or more AttributeValue sub-elements that list the roles that can be assumed by a user in your IdP. The value of the AttributeValue sub-element is a comma-delimited pair of role Alibaba Cloud Resource Name (ARN) and IdP ARN. You can view the role ARN and IdP ARN in the RAM console.
  - To view the role ARN, go to the RAM Roles page and click the name of the target RAM role. You can view the role ARN in the Basic Information section.
  - To view the IdP ARN, go to the SSO page. On the Role-based SSO tab, click the name of the target IdP. You can view the IdP ARN in the IdP Information section.
  Note If a role attribute contains multiple AttributeValue sub-elements, the user must select which role to assume when the user logs on to the console.
  
  The following script provides an example of the Role attribute:
```
<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 The value of $account_id is the ID of the Alibaba Cloud account that defines the RAM role and IdP.
- RoleSessionName attribute: an Attribute element with the Name attribute set to https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName
  Required. This element contains only one AttributeValue sub-element that specifies the user information to be displayed in the RAM console and ActionTrail logs. If you want multiple users to assume the same role, set different values of the RoleSessionName attribute for the users. Each value uniquely identifies a user. For example, you can set the value to an employee ID or email address.
  
  The value in the AttributeValue sub-element must be 2 to 32 characters in length and can contain only letters, digits, and the following special characters: -_. @=.
  
  The following script provides an example of the RoleSessionName attribute:
```
<Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName">
  <AttributeValue>user_id</AttributeValue>
</Attribute>                     
```
- SessionDuration attribute: an Attribute element with the Name attribute set to https://www.aliyun.com/SAML-Role/Attributes/SessionDuration
  Optional. This element contains only one AttributeValue sub-element that specifies the maximum duration of the session. The value of the sub-element is an integer, in seconds. The value cannot exceed the maximum session duration that is specified for the role. The minimum value is 900 seconds.
  
  The following script provides an example of the SessionDuration attribute:
```
<Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/SessionDuration">
  <AttributeValue>1800</AttributeValue>
</Attribute>                  
```
Maximum role session duration
If you use the console to assume a role, the maximum duration of the role session depends on the SessionDuration attribute that is specified in the SAML assertion. If the SessionNotOnOrAfter attribute of the AuthnStatement element is also specified, the maximum session duration depends on the smaller value of SessionDuration and SessionNotOnOrAfter. If neither SessionDuration nor SessionNotOnOrAfter is specified, the maximum session duration depends on the smaller value between the Maximum Session Duration parameter of the role and the Logon Session Valid For parameter. For more information, see Set security policies for RAM users and Set the maximum session duration for a RAM role.

If you call the AssumeRoleWithSAML operation to assume a role, STS determines the maximum duration of the role session based on the parameter values. If you have specified the DurationSeconds parameter when calling the operation and defined the SessionNotOnOrAfter attribute in the AuthnStatement element, the maximum session duration depends on the smaller value of SessionDuration and SessionNotOnOrAfter. If neither SessionDuration nor SessionNotOnOrAfter is specified, the default maximum session duration is 3,600 seconds.