全部產品
Search
文件中心

Resource Access Management:AssumeRole

更新時間:Oct 26, 2026

透過呼叫AssumeRole介面,取得一個扮演RAM角色的臨時身分憑證(STS Token)。

介面說明

應用場景

  • 臨時授權存取:通常情況下,建議您透過伺服器端呼叫 API,盡可能保證存取金鑰不被洩漏。但是有些上傳檔案的場景最好採用用戶端直傳的形式,避免伺服器端中轉帶來的多餘開銷。此時,可以由伺服器端下發臨時安全權杖(STS Token),用戶端透過臨時安全權杖(STS Token)進行資源直傳。更多資訊,請參見行動應用使用臨時安全權杖存取阿里雲。

  • 跨帳號存取:當您擁有多個阿里雲帳號,例如:帳號 A 和帳號 B,希望實現帳號 B 存取帳號 A 的指定資源。此時,您可以在帳號 A 下建立可信實體為帳號 B 的 RAM 角色,並授權允許帳號 B 下的某個 RAM 使用者或 RAM 角色可以扮演該角色,然後透過該角色存取帳號 A 的指定資源。更多資訊,請參見跨阿里雲帳號存取資源。

前提條件

該介面不能使用阿里雲帳號(主帳號)呼叫,只能使用 RAM 使用者或 RAM 角色呼叫,請確保已為呼叫者(RAM 使用者或 RAM 角色)授予 STS 角色扮演權限(AliyunSTSAssumeRoleAccess)。

否則,會顯示如下錯誤:

You are not authorized to do this action. You should be authorized by RAM.

問題原因和解決方法如下:

最佳實務

STS Token 自核發後將在一段時間內有效,建議您設定合理的 Token 有效期限,並在有效期限內重複使用,以避免業務請求速率上升後,STS Token 核發的速率限制影響到業務。具體速率限制,請參見 STS 服務呼叫次數是否有上限。您可以透過請求參數DurationSeconds設定 Token 有效期限。

在行動裝置端上傳或下載 OSS 檔案等場景下,其存取量較大,即使重複使用 STS Token 也可能無法滿足限流要求。為避免 STS 的限流成為 OSS 存取量的瓶頸,您可以嘗試 OSS 的在 URL 中包含簽章的方案。更多資訊,請參見在 URL 中包含簽章和伺服器端簽章後直傳。

調試

您可以在OpenAPI Explorer中直接運行該介面,免去您計算簽名的困擾。運行成功後,OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊,可以在RAM權限原則語句的Action元素中使用,用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下:

  • 操作:是指具體的許可權點。

  • 存取層級:是指每個操作的存取層級,取值為寫入(Write)、讀取(Read)或列出(List)。

  • 資源類型:是指操作中支援授權的資源類型。具體說明如下:

    • 對於必選的資源類型,用前面加 * 表示。

    • 對於不支援資源級授權的操作,用全部資源表示。

  • 條件關鍵字:是指雲產品自身定義的條件關鍵字。

  • 關聯操作:是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權,操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

sts:AssumeRole

get

*Role

acs:ram::{#accountId}:role/{#RoleName}

  • sts:SourceIdentity
  • sts:SetSourceIdentity

請求參數

名稱

類型

必填

描述

樣本值

DurationSeconds

integer

否

Token 有效期限。單位:秒。

Token 有效期限最小值為 900 秒,最大值為要扮演角色的MaxSessionDuration時間。預設值為 3600 秒。

您可以透過 CreateRole 或 UpdateRole 設定角色最大工作階段時間MaxSessionDuration。更多資訊,請參見 CreateRole 或 UpdateRole 。

3600

Policy

string

否

為 STS Token 額外新增的一個權限原則,進一步限制 STS Token 的權限。具體如下:

  • 如果指定該權限原則,則 STS Token 最終的權限原則取 RAM 角色權限原則與該權限原則的交集。

  • 如果不指定該權限原則,則 STS Token 最終的權限原則取 RAM 角色的權限原則。

長度為 1~2048 個字元。

關於權限原則元素和範例,請參見權限原則基本元素和權限原則範例庫。

{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}

RoleArn

string

是

要扮演的 RAM 角色 ARN。

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

格式:acs:ram::<account_id>:role/<role_name> 。

您可以透過 RAM 主控台或 API 檢視角色 ARN。具體如下:

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

RoleSessionName

string

是

角色工作階段名稱。

該參數為使用者自訂參數。通常設定為呼叫該 API 的使用者身分,例如:使用者名稱。在操作稽核日誌中,即使是同一個 RAM 角色執行的操作,也可以根據不同的RoleSessionName來區分實際操作者,以實現使用者層級的存取稽核。

長度為 2~64 個字元,可包含英文字母、數字和特殊字元.@-_。

alice

ExternalId

string

否

角色外部 ID。

該參數為外部提供的用於表示角色的參數資訊,主要功能是防止混淆代理人問題。更多資訊,請參見使用 ExternalId 防止混淆代理人問題。

長度為 2~1224 個字元,可包含英文字母、數字和特殊字元=,.@:/-_。正規表示式為:[\w+=,.@:\/-]*。

abcd1234

SourceIdentity

string

否

來源身分資訊。

在扮演角色時,可以指定扮演者的來源身分(SourceIdentity)作為工作階段的初始身分標識。該來源身分的值在持續扮演角色的鏈結工作階段中將一直存在,中途不可變更,可確保操作的可追溯性和安全性。

SourceIdentity 長度為 2~64 個字元,可包含英文字母、數字、以及特殊字元:=,.@-_。正規表示式為:[\w+=,.@-]*。您不能使用以acs:、aliyun:、alibabacloud: 開頭的值,這些首碼為阿里雲內部使用。

Alice

關於公用請求參數的詳情,請參見公用請求參數。

返回參數

名稱

類型

描述

樣本值

object

返回參數。

RequestId

string

請求 ID。

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

AssumedRoleUser

object

角色扮演時的臨時身分。

AssumedRoleId

string

臨時身分的 ID。

34458433936495****:alice

Arn

string

臨時身分的 ARN。

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

Credentials

object

存取憑證。

SecurityToken

string

安全權杖。

說明

安全權杖的長度不固定,我們強烈建議您不要對安全權杖的最大長度做任何限制。

********

Expiration

string

Token 到期失效時間(UTC 時間)。

2015-04-09T11:52:19Z

AccessKeySecret

string

存取金鑰。

wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****

AccessKeyId

string

存取金鑰 ID。

STS.L4aBSCSJVMuKg5U1****

SourceIdentity

string

來源身分資訊。

在扮演角色時,可以指定扮演者的來源身分(SourceIdentity)作為工作階段的初始身分標識。該來源身分的值在持續扮演角色的鏈結工作階段中將一直存在,中途不可變更,可確保操作的可追溯性和安全性。

如果沒有設定來源身分資訊,則該欄位不會傳回。

Alice

樣本

正常返回樣本

JSON格式

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

錯誤碼

HTTP status code

錯誤碼

錯誤資訊

描述

400 InvalidParameter.DurationSeconds The Min/Max value of DurationSeconds is 15min/1hr. DurationSeconds 參數不合法,DurationSeconds 最小值為 15 分鐘,最大值為 1 小時。
400 InvalidParameter.ExternalId The parameter ExternalId is wrongly formed. 參數 ExternalId 不合法。
400 InvalidParameter.RoleArn The parameter RoleArn is wrongly formed. 參數 RoleArn 不能為空值。
400 InvalidParameter.RoleSessionName The parameter RoleSessionName is wrongly formed. 參數 RoleSessionName 格式錯誤。
400 InvalidParameter.SerialNumber The parameter SerialNumber is wrongly formed.
400 InvalidParameter.TokenCode The parameter TokenCode is wrongly formed.
400 InvalidParameter.PolicyGrammar The parameter Policy has not passed grammar check. 參數 Policy 語法格式檢查未通過。
400 InvalidParameter.PolicySize The size of Policy must be smaller than 2048 bytes. Policy 參數不合法,Policy 長度必須小於 2048 位元組。
400 InvalidParameter.ContentType The ContentType request header must be either "application/json" or "application/x-www-form-urlencoded".
500 InternalError STS Server Internal Error happened, please send the RequestId to us. 發生內部錯誤。
403 NoPermission You are not authorized to do this action. You should be authorized by RAM.
403 AuthenticationFail.ApiUsername The specified api username is not legal.
403 AuthenticationFail.ApiPassword The specified api password is not legal.
404 EntityNotExist.Role The specified Role not exists .

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊,參考變更詳情。