Obtains a Security Token Service (STS) token to assume a Resource Access Management (RAM) role during role-based single sign-on (SSO) by using Security Assertion Markup Language (SAML).

Prerequisites

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AssumeRoleWithSAML

The operation that you want to perform. Set the value to AssumeRoleWithSAML.

SAMLProviderArn String Yes acs:ram::123456789012****:saml-provider/company1

The Alibaba Cloud Resource Name (ARN) of the SAML IdP that is created in the RAM console.

Format: acs:ram::<account_id>:saml-provider/<saml_provider_id>.

You can view the ARN in the RAM console or by calling operations.

RoleArn String Yes acs:ram::123456789012****:role/adminrole

The ARN of the RAM role.

The trust entity of the RAM role is a SAML IdP. For more information, see Create a RAM role for a trusted IdP or CreateRole.

Format: acs:ram::<account_id>:role/<role_name>.

You can view the ARN in the RAM console or by calling operations.

SAMLAssertion String Yes base64_encoded_saml_assertion

The Base64-encoded SAML assertion.

The value must be 4 to 100,000 characters in length.

Note A complete SAML response rather than a single SAMLAssertion field must be retrieved from the external IdP.
Policy String No url_encoded_policy

The policy that specifies the permissions of the returned STS token. You can use this parameter to grant the STS token fewer permissions than the permissions granted to the RAM role.

  • If you specify this parameter, the permissions of the returned STS token are the permissions that are included in the value of this parameter and owned by the RAM role.
  • If you do not specify this parameter, the returned STS token has all the permissions of the RAM role.

The value must be 1 to 1,024 characters in length.

DurationSeconds Long No 3600

The validity period of the STS token. Unit: seconds.

Minimum value: 900. Maximum value: the value of the MaxSessionDuration parameter. Default value: 3600.

You can call the CreateRole or UpdateRole operation to configure the MaxSessionDuration parameter. For more information, see CreateRole or UpdateRole.

Note Anonymous users can call the AssumeRoleWithSAML operation because authentication for this operation is performed based on SAML assertions. Therefore, you do not need to specify the following common parameters: Signature, SignatureMethod, SignatureVersion, and AccessKeyId.

Response parameters

Parameter Type Example Description
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F

The ID of the request.

SAMLAssertionInfo Object

The information in the SAML assertion.

SubjectType String persistent

The Format attribute of the NameID element in the SAML assertion. If the Format attribute is prefixed with urn:oasis:names:tc:SAML:2.0:nameid-format:, the prefix is not included in the value of this parameter. For example, if the value of the Format attribute is urn:oasis:names:tc:SAML:2.0:nameid-format:persistent/transient, the value of this parameter is persistent/transient.

Subject String alice@example.com

The value in the NameID sub-element of the Subject element in the SAML assertion.

Issuer String http://example.com/adfs/services/trust

The value in the Issuer element in the SAML assertion.

Recipient String https://signin.aliyun.com/saml-role/SSO

The Recipient attribute of the SubjectConfirmationData sub-element. SubjectConfirmationData is a sub-element of the Subject element in the SAML assertion.

AssumedRoleUser Object

The temporary identity that you use to assume the RAM role.

AssumedRoleId String 34458433936495****:alice

The ID of the temporary identity that you use to assume the RAM role.

Arn String acs:sts::123456789012****:assumed-role/AdminRole/alice

The ARN of the temporary identity that you use to assume the RAM role.

Credentials Object

The access credentials.

SecurityToken String ********

The STS token.

Expiration String 2015-04-09T11:52:19Z

The time when the STS token expires. The time is displayed in UTC.

AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****

The AccessKey secret.

AccessKeyId String STS.L4aBSCSJVMuKg5U1****

The AccessKey ID.

Examples

Sample requests

https://sts.aliyuncs.com/?Action=AssumeRoleWithSAML
&SAMLProviderArn=acs:ram::123456789012****:saml-provider/company1
&RoleArn=acs:ram::123456789012****:role/adminrole
&SAMLAssertion=base64_encoded_saml_assertion
&DurationSeconds=3600
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<AssumeRoleWithSAMLResponse>
    <Credentials>
        <AccessKeyId>STS.L4aBSCSJVMuKg5U1****</AccessKeyId>
        <AccessKeySecret>wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****</AccessKeySecret>
        <Expiration>2015-04-09T11:52:19Z</Expiration>
        <SecurityToken>********</SecurityToken>
    </Credentials>
    <AssumedRoleUser>
        <arn>acs:sts::1234567890123456:assumed-role/AdminRole/alice</arn>
        <AssumedRoleId>34458433936495****:alice</AssumedRoleId>
    </AssumedRoleUser>
    <SAMLAssertionInfo>
        <SubjectType>persistent</SubjectType>
        <Subject>alice@example.com</Subject>
        <Recipient>https://signin.aliyun.com/saml-role/SSO</Recipient>
        <Issuer>http://example.com/adfs/services/trust</Issuer>
    </SAMLAssertionInfo>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
</AssumeRoleWithSAMLResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "Credentials" : {
    "AccessKeyId" : "STS.L4aBSCSJVMuKg5U1****",
    "AccessKeySecret" : "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
    "Expiration" : "2015-04-09T11:52:19Z",
    "SecurityToken" : "********"
  },
  "AssumedRoleUser" : {
    "arn" : "acs:sts::1234567890123456:assumed-role/AdminRole/alice",
    "AssumedRoleId" : "34458433936495****:alice"
  },
  "SAMLAssertionInfo" : {
    "SubjectType" : "persistent",
    "Subject" : "alice@example.com",
    "Recipient" : "https://signin.aliyun.com/saml-role/SSO",
    "Issuer" : "http://example.com/adfs/services/trust"
  },
  "RequestId" : "6894B13B-6D71-4EF5-88FA-F32781734A7F"
}

Error codes

For a list of error codes, visit the API Error Center.