Obtains a temporary identity to assume a RAM role during role-based single sign-on (SSO).

Request parameters

Note Anonymous users can call the AssumeRoleWithSAML API 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.
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 identity provider (IdP). The IdP must be configured in the RAM console. Format: acs:ram::$account_ID:saml-provider/$saml_provider_ID.
RoleArn String Yes acs:ram::123456789012****:role/adminrole The ARN of the RAM role to be assumed. Format: acs:ram::$accountID:role/$roleName.
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 instead of a single SAMLAssertion field must be retrieved from the 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 those granted to the RAM role. If you do not specify this parameter, the returned STS token has all 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.

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

Response parameters

Parameter Type Example Description
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F The ID of the request.
Credentials The access credentials.
AccessKeyId String STS.L4aBSCSJVMuKg5U1**** The AccessKey ID.
AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK**** The AccessKey secret.
SecurityToken String ******** The STS token.
Expiration String 2015-04-09T11:52:19Z The time when the STS token expires.
AssumedRoleUser 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. Format: acs:ram::$accountID:assumed-role/$roleName/$roleSessionName.
AssumedRoleUserId String 34458433936495****:alice The ID of the temporary identity that you use to assume the RAM role.
SAMLAssertionInfo 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:persistant/transient, the value of this parameter is persistant/transient.
Subject String alice@example.com The value in the NameID sub-element of the Subject 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.
Issuer String http://example.com/adfs/services/trust The value in the Issuer element in the SAML assertion.

Examples

Note If you use the GET method to send an API request and the SAMLAssertion parameter in the API request is set to a value with a large size, the API request may fail. We recommend that you use the POST method to send the API request.

Sample success responses

XML format

<AssumeRoleResponse>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
    <AssumedRoleUser>
        <arn>acs:sts::123456789012****:assumed-role/AdminRole/alice</arn>
        <AssumedRoleUserId>34458433936495****:alice</AssumedRoleUserId>
    </AssumedRoleUser>
    <Credentials>
        <AccessKeyId>STS.L4aBSCSJVMuKg5U1****</AccessKeyId>
        <AccessKeySecret>wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****</AccessKeySecret>
        <SecurityToken>********</SecurityToken>    
        <Expiration>2015-04-09T11:52:19Z</Expiration>
    </Credentials>
    <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>
</AssumeRoleResponse>         

JSON format

{
    "Credentials": {
        "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****",
        "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
        "Expiration": "2015-04-09T11:52:19Z",
        "SecurityToken": "********"
    },
    "AssumedRoleUser": {
        "arn": "acs:sts::1234567890123456:assumed-role/AdminRole/alice",
        "AssumedRoleUserId":"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

HTTP status code Error code Error message Description
400 MissingParameter.SAMLAssertion Parameter SAMLAssertion is required. The error message returned because the SAMLAssertion parameter is not specified.
400 MissingParameter.SAMLProviderArn Parameter SAMLProviderArn is required. The error message returned because the SAMLProviderArn parameter is not specified.
400 MissingParameter.RoleArn Parameter RoleArn is required. The error message returned because the RoleArn parameter is not specified.
400 InvalidParameter.PolicyGrammar Invalid Policy. The error message returned because the specified policy is invalid.
400 InvalidParameter.PolicySize The max size of policy string is 1024. The error message returned because the length of the specified policy script has reached the upper limit. The policy script can be up to 1,024 characters in length.
400 InvalidParameter.RoleSessionName The RoleSessionName is invalid. The error message returned because the specified role session name is invalid.
400 InvalidParameter.DurationSeconds The DurationSeconds is invalid. The error message returned because the specified value for the DurationSeconds parameter is invalid.
404 EntityNotExist.SAMLProvider Can not find SAML provider. The error message returned because the specified SAML IdP does not exist.
404 EntityNotExist.RoleArn The specified Role does not exists. The error message returned because the specified RAM role does not exist.
401 AuthenticationFail.IDPMetadata.Invalid The IdP Metadata of your SAML Provider is invalid. The error message returned because the metadata of the SAML IdP is invalid.
401 AuthenticationFail.SAMLAssertion.Expired The SAML Assertion is expired. The error message returned because the SAML assertion has expired.
401 AuthenticationFail.SAMLAssertion.Invalid The SAML Assertion is invalid. The error message returned because the SAML assertion is invalid.