RAM使用者調用AssumeRole介面擷取一個扮演RAM角色的臨時身份憑證（STS Token）。該介面中RAM使用者扮演的是可信實體為阿里雲帳號類型的RAM角色。

使用限制

  • 本介面僅限具有STS角色扮演許可權的RAM使用者使用。沒有許可權時會報錯，報錯資訊如下：
    You are not authorized to do this action. You should be authorized by RAM.

    問題原因和解決方案如下：

  • 本介面調用次數限制：每分鐘最多調用6000次，且一個阿里雲帳號及該帳號下的RAM使用者、RAM角色共用這6000次。
    當請求量超過6000次時，超出部分會報錯，報錯資訊如下：
    Request was denied due to user flow control.

請求參數

名稱 類型 是否必選 樣本值 描述
Action String 是 AssumeRole 要執行的操作。取值：AssumeRole
RoleArn String 是 acs:ram::123456789012****:role/adminrole 要扮演的RAM角色ARN。

該角色是可信實體為阿里雲帳號類型的RAM角色。更多資訊，請參見建立可信實體為阿里雲帳號的RAM角色或CreateRole。

格式：acs:ram::$accountID:role/$roleName 。

说明 您可以通過RAM控制台或API查看角色ARN。具體如下：
RoleSessionName String 是 alice

角色會話名稱。

該參數為使用者自訂參數。通常設定為調用該API的使用者身份，例如：使用者名稱。在Action Trail日誌中，即使是同一個RAM角色執行的操作，也可以根據不同的RoleSessionName來區分實際操作者，以實現使用者層級的訪問審計。

長度為2~64個字元，可包含英文字母、數字、半形句號（.）、at（@）、短劃線（-）和底線（_）。
Policy String 否 {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
為STS Token額外添加的一個權限原則，進一步限制STS Token的許可權。具體如下：
  • 如果指定該權限原則，則STS Token最終的權限原則取RAM角色權限原則與該權限原則的交集。
  • 如果不指定該權限原則，則STS Token最終的權限原則取RAM角色的權限原則。

長度為1~1024個字元。
DurationSeconds Long 否 3600

到期時間。單位：秒。

到期時間最小值為900秒，最大值為要扮演角色的MaxSessionDuration時間。預設值為3600秒。

说明 您可以通過CreateRole或UpdateRole介面設定角色最大會話時間MaxSessionDuration。詳情請參見CreateRole或UpdateRole。

返回資料

名稱 類型 樣本值 描述
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F 請求ID。
Credentials 訪問憑證。
└AccessKeyId String STS.L4aBSCSJVMuKg5U1**** 存取金鑰ID。
└AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK**** 存取金鑰。
└SecurityToken String ******** 安全性權杖。
└Expiration String 2015-04-09T11:52:19Z 失效時間。
AssumedRoleUser 角色扮演時的臨時身份。
└Arn String acs:ram::123456789012****:role/adminrole/alice 臨時身份的ARN。
└AssumedRoleId String 34458433936495****:alice 臨時身份的ID。

樣本

請求樣本

https://sts.aliyuncs.com/?Action=AssumeRole
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&DurationSeconds=3600
&<公用請求參數>
说明 關於公用請求參數的詳情，請參見公用參數。

正常返回樣本

XML格式 

<AssumeRoleResponse>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
    <AssumedRoleUser>
        <Arn>acs:ram::123456789012****:role/adminrole/alice</arn>
        <AssumedRoleId>34458433936495****:alice</AssumedRoleId>
    </AssumedRoleUser>
    <Credentials>
        <AccessKeyId>STS.L4aBSCSJVMuKg5U1****</AccessKeyId>
        <AccessKeySecret>wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****</AccessKeySecret>
        <SecurityToken>********</SecurityToken>
        <Expiration>2015-04-09T11:52:19Z</Expiration>
    </Credentials>
</AssumeRoleResponse>

JSON格式 

{
    "Credentials": {
        "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****",
        "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
        "Expiration": "2015-04-09T11:52:19Z",
        "SecurityToken": "********"
    },
    "AssumedRoleUser": {
        "Arn": "acs:ram::123456789012****:role/adminrole/alice",
        "AssumedRoleId":"34458433936495****:alice"
        },
    "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F"
}

錯誤碼

HttpCode 錯誤碼 錯誤資訊 描述
400 InvalidParameter The parameter RoleArn is wrongly formed. 角色ARN格式錯誤。
400 InvalidParameter.RoleArn The parameter RoleArn is wrongly formed. 角色ARN格式錯誤。
400 InvalidParameter.RoleSessionName The parameter RoleSessionName is wrongly formed. RoleSessionName格式錯誤，支援輸入2~64個字元，請輸入至少2個字元，允許輸入英文字母、數字、半形句號（.）、at（@）、短劃線（-）和底線（_）。
400 InvalidParameter.DurationSeconds The Min/Max value of DurationSeconds is 15min/1hr. DurationSeconds參數設定錯誤，到期時間最小值為900秒，最大值為MaxSessionDuration設定的時間。
400 InvalidParameter.PolicyGrammar The parameter Policy has not passed grammar check. 權限原則語法錯誤。
400 InvalidParameter.PolicySize The size of Policy must be smaller than 1024 bytes. 權限原則長度超限，最大不超過1024字元。
403 NoPermission You are not authorized to do this action. You should be authorized by RAM. STS Token沒有許可權。解決方案請參見為什麼使用STS時會報錯。
404 EntityNotExist.Role The specified Role not exists. 指定的RAM角色不存在。
500 InternalError STS Server Internal Error happened. 伺服器內部錯誤。

後續步驟

獲得扮演RAM角色的STS Token後，RAM使用者便可以使用STS Token，開始以RAM角色身份訪問阿里雲資源。