透過呼叫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 扮演角色的權限原則:請為該呼叫者新增系統原則(AliyunSTSAssumeRoleAccess)或自訂原則。具體操作,請參見能否指定 RAM 使用者具體可以扮演哪個 RAM 角色、為 RAM 使用者授權。
RAM 角色的信任原則不包含呼叫者,即 RAM 角色不允許該呼叫者扮演:請為 RAM 角色新增允許該呼叫者扮演的信任原則。具體操作,請參見修改 RAM 角色的信任原則。
最佳實務
STS Token 自核發後將在一段時間內有效,建議您設定合理的 Token 有效期限,並在有效期限內重複使用,以避免業務請求速率上升後,STS Token 核發的速率限制影響到業務。具體速率限制,請參見 STS 服務呼叫次數是否有上限。您可以透過請求參數DurationSeconds設定 Token 有效期限。
在行動裝置端上傳或下載 OSS 檔案等場景下,其存取量較大,即使重複使用 STS Token 也可能無法滿足限流要求。為避免 STS 的限流成為 OSS 存取量的瓶頸,您可以嘗試 OSS 的在 URL 中包含簽章的方案。更多資訊,請參見在 URL 中包含簽章和伺服器端簽章後直傳。
調試
您可以在OpenAPI Explorer中直接運行該介面,免去您計算簽名的困擾。運行成功後,OpenAPI Explorer可以自動產生SDK程式碼範例。
調試
授權資訊
|
操作 |
存取層級 |
資源類型 |
條件關鍵字 |
關聯操作 |
|
sts:AssumeRole |
get |
*Role
|
|
|
請求參數
|
名稱 |
類型 |
必填 |
描述 |
樣本值 |
| DurationSeconds |
integer |
否 |
Token 有效期限。單位:秒。 Token 有效期限最小值為 900 秒,最大值為要扮演角色的 您可以透過 CreateRole 或 UpdateRole 設定角色最大工作階段時間 |
3600 |
| Policy |
string |
否 |
為 STS Token 額外新增的一個權限原則,進一步限制 STS Token 的權限。具體如下:
長度為 1~2048 個字元。 |
{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"} |
| RoleArn |
string |
是 |
要扮演的 RAM 角色 ARN。 該角色是可信實體為阿里雲帳號類型的 RAM 角色。更多資訊,請參見建立可信實體為阿里雲帳號的 RAM 角色或 CreateRole 。 格式: 您可以透過 RAM 主控台或 API 檢視角色 ARN。具體如下:
|
acs:ram::123456789012****:role/adminrole |
| RoleSessionName |
string |
是 |
角色工作階段名稱。 該參數為使用者自訂參數。通常設定為呼叫該 API 的使用者身分,例如:使用者名稱。在操作稽核日誌中,即使是同一個 RAM 角色執行的操作,也可以根據不同的 長度為 2~64 個字元,可包含英文字母、數字和特殊字元 |
alice |
| ExternalId |
string |
否 |
角色外部 ID。 該參數為外部提供的用於表示角色的參數資訊,主要功能是防止混淆代理人問題。更多資訊,請參見使用 ExternalId 防止混淆代理人問題。 長度為 2~1224 個字元,可包含英文字母、數字和特殊字元 |
abcd1234 |
| SourceIdentity |
string |
否 |
來源身分資訊。 在扮演角色時,可以指定扮演者的來源身分(SourceIdentity)作為工作階段的初始身分標識。該來源身分的值在持續扮演角色的鏈結工作階段中將一直存在,中途不可變更,可確保操作的可追溯性和安全性。 SourceIdentity 長度為 2~64 個字元,可包含英文字母、數字、以及特殊字元: |
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 . |
訪問錯誤中心查看更多錯誤碼。
變更歷史
更多資訊,參考變更詳情。