AssumeRoleWithSAML - Resource Access Management - Alibaba Cloud Documentation Center

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

Operation Description

Prerequisites

A SAML response is obtained from an external identity provider (IdP).
A SAML IdP is created in the RAM console. For more information, see Create a SAML IdP or CreateSAMLProvider.
A RAM role whose trusted entity is a SAML IdP is created in the RAM console. For more information, see Create a RAM role for a trusted IdP or CreateRole.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

Parameter	Type	Required	Description	Example
SAMLProviderArn	string	Yes	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. For more information about how to view the ARN in the RAM console, see How do I view the ARN of a RAM role? For more information about how to view the ARN by calling operations, see GetSAMLProvider or ListSAMLProviders.	acs:ram::123456789012****:saml-provider/company1
RoleArn	string	Yes	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. For more information about how to view the ARN in the RAM console, see How do I view the ARN of the RAM role?. For more information about how to view the ARN by calling operations, see ListRoles or GetRole.	acs:ram::123456789012****:role/adminrole
SAMLAssertion	string	Yes	The Base64-encoded SAML assertion. The value must be 4 to 100,000 characters in length. NoteA complete SAML response rather than a single SAMLAssertion field must be retrieved from the external IdP.	base64_encoded_saml_assertion
Policy	string	No	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 2,048 characters in length.	url_encoded_policy
DurationSeconds	long	No	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.	3600

NoteAnonymous 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	Description	Example
	object	The response parameters.
RequestId	string	The ID of the request.	6894B13B-6D71-4EF5-88FA-F32781734A7F
SAMLAssertionInfo	object	The information in the SAML assertion.
SubjectType	string	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`.	persistent
Subject	string	The value in the NameID sub-element of the `Subject` element in the SAML assertion.	alice@example.com
Issuer	string	The value in the `Issuer` element in the SAML assertion.	http://example.com/adfs/services/trust
Recipient	string	The `Recipient` attribute of the SubjectConfirmationData sub-element. SubjectConfirmationData is a sub-element of the `Subject` element in the SAML assertion.	https://signin.aliyun.com/saml-role/SSO
AssumedRoleUser	object	The temporary identity that you use to assume the RAM role.
AssumedRoleId	string	The ID of the temporary identity that you use to assume the RAM role.	34458433936495****:alice
Arn	string	The ARN of the temporary identity that you use to assume the RAM role.	acs:sts::123456789012****:assumed-role/AdminRole/alice
Credentials	object	The access credentials.
SecurityToken	string	The STS token.	********
Expiration	string	The time when the STS token expires. The time is displayed in UTC.	2015-04-09T11:52:19Z
AccessKeySecret	string	The AccessKey secret.	wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyId	string	The AccessKey ID.	STS.L4aBSCSJVMuKg5U1****

Example

Request example

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

Normal return example

JSONFormat

{
  "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"
}

XMLFormat

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

Error codes

Http code	Error code	Error message
500	InternalError	STS Server Internal Error happened, please send the RequestId to us.
500	InternalError	STS Server Internal Error happened, please send the RequestId to us.

For a list of error codes, visit the API error center.