All Products
Search
Document Center

Resource Access Management:AssumeRoleWithSAML

Last Updated:Nov 10, 2022

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

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
SAMLProviderArnstringYes

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.

acs:ram::123456789012****:saml-provider/company1
RoleArnstringYes

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.

acs:ram::123456789012****:role/adminrole
SAMLAssertionstringYes

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
PolicystringNo

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
DurationSecondslongNo

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

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The ID of the request.

6894B13B-6D71-4EF5-88FA-F32781734A7F
SAMLAssertionInfoobject

The information in the SAML assertion.

SubjectTypestring

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
Subjectstring

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

alice@example.com
Issuerstring

The value in the Issuer element in the SAML assertion.

http://example.com/adfs/services/trust
Recipientstring

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
AssumedRoleUserobject

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

AssumedRoleIdstring

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

34458433936495****:alice
Arnstring

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

acs:sts::123456789012****:assumed-role/AdminRole/alice
Credentialsobject

The access credentials.

SecurityTokenstring

The STS token.

********
Expirationstring

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

2015-04-09T11:52:19Z
AccessKeySecretstring

The AccessKey secret.

wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyIdstring

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 codeError codeError message
500InternalErrorSTS Server Internal Error happened, please send the RequestId to us.
500InternalErrorSTS Server Internal Error happened, please send the RequestId to us.

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