通过调用AssumeRole接口,获取一个扮演RAM角色的临时身份凭证(STS Token)。
接口说明
前提条件
该接口不能使用阿里云账号(主账号)调用,只能使用 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代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
sts:AssumeRole | get |
|
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
DurationSeconds | long | 否 | Token 有效期。单位:秒。 Token 有效期最小值为 900 秒,最大值为要扮演角色的 您可以通过 CreateRole 或 UpdateRole 设置角色最大会话时间 | 3600 |
Policy | string | 否 | {"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 |
关于公共请求参数的详情,请参见公共请求参数。
返回参数
示例
正常返回示例
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****"
}
}
错误码
HTTP status code | 错误码 | 错误信息 |
---|---|---|
400 | InvalidParameter.DurationSeconds | The Min/Max value of DurationSeconds is 15min/1hr. |
400 | InvalidParameter.ExternalId | The parameter ExternalId is wrongly formed. |
400 | InvalidParameter.RoleArn | The parameter RoleArn is wrongly formed. |
400 | InvalidParameter.RoleSessionName | The parameter RoleSessionName is wrongly formed. |
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. |
400 | InvalidParameter.PolicySize | The size of Policy must be smaller than 2048 bytes. |
400 | InvalidParameter.ContentType | The ContentType request header must be either "application/json" or "application/x-www-form-urlencoded". |
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. |
403 | NoPermission | No permission perform sts:AssumeRole on this Role. Maybe you are not authorized to perform sts:AssumeRole or the specified role does not trust you |
403 | NoPermission | Roles may not be assumed by root accounts. |
404 | EntityNotExist.Role | The specified Role not exists . |
500 | InternalError | STS Server Internal Error happened, please send the RequestId to us. |
500 | InternalError | STS Server Internal Error happened, please send the RequestId to us. |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2022-09-27 | OpenAPI 错误码发生变更 | 查看变更详情 |