通过调用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 | Write |
|
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
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 错误码发生变更 | 看变更集 | ||||||||||
|