AssumeRole - 角色扮演--访问控制-火山引擎

文档中心

立即注册

导航

AssumeRole - 角色扮演

最近更新时间：2024.09.26 12:19:22首次发布时间：2021.12.21 14:07:34

以角色身份发起一次临时会话，临时会话中包含一组短效安全凭证用于请求云服务API。

注意事项

该接口不能通过主账号访问，使用IAM子用户访问时需要为用户添加AssumeRole的访问权限（可授予系统预设策略STSAssumeRoleAccess）。
使用角色会话的临时安全凭证请求云服务API时，需要将SessionToken作为公共参数放在Header中，参考公共参数文档。
角色扮演接口的限流为200次/秒。若您的业务的并发要求较高时，建议您调高角色最大会话时长（最长12小时），同时在请求AssumeRole时将DurationSeconds设置为一个较高的值，并在这段时间内重复利用临时安全凭证。
对于在客户端上传或下载TOS文件等场景，可以使用URL预签名方案，将客户端请求提前进行签名并生成请求URL下发至客户端。

请求说明

此接口的Service为sts，接入地址为：sts.volcengineapi.com。建议使用SDK进行请求。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

参数	类型	是否必填	示例值	描述
Action	String	是	AssumeRole	要执行的操作，取值：AssumeRole。
Version	String	是	2018-01-01	API的版本，取值：2018-01-01。
RoleTrn	String	是	trn:iam::2000012345:role/my_role	需要扮演的角色Trn，格式为`trn:iam::${AccountId}:role/${RoleName}`。其中`${AccountId}`需要填入角色所属的主账号ID，`${RoleName}`需要填入实际的角色名称。例如账号ID为2000012345的账号内角色名为myRole的角色对应的RoleTrn为`trn:iam::2000012345:role/myRole`
RoleSessionName	String	是	bob	角色会话名称，长度2-64字符，支持英文、数字和.-_@符号。对于同一个角色，在每次扮演时可以指定不同的会话名称，从而达到区分会话的目的。该字段也会在云审计中体现，方便从审计日志中区分不同会话的访问记录。
DurationSeconds	Integer	否	3600	临时密钥有效时长（单位：秒），最短支持900，最长支持43200。若未传入该值或传入的值小于900，则默认按3600执行，若传入的值大于43200，则默认按43200执行。
Policy	String	否	{ "Statement": [ { "Effect": "Allow", "Action": [ "vpc:CreateVpc" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "volc:RequestedRegion": [ "cn-beijing" ] } } } ] }	角色内联策略，用于进一步限制临时凭证的权限。如果内联权限策略不为空，则临时凭证的实际权限为所扮演角色的权限策略与内联权限策略的交集。策略语法格式同普通的IAM策略，可参考策略语法介绍。
Tags.N.Key	Array of String	否	env	标签键。至多附加50对标签。使用UTF-8编码的Unicode，长度为1~128字符，允许任何语言文字、数字、空格和_ . : / = + - @符号。
Tags.N.Value	Array of String	否	dev	标签值。至多附加50对标签。使用UTF-8编码的Unicode，长度为0~256字符（即Value可以为空），允许任何语言文字、数字、空格和_ . : / = + - @符号。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
Credentials	Object	请参考数据结构内具体参数示例值。	角色扮演产生的临时安全凭证。
AssumedRoleUser	Object	请参考数据结构内具体参数示例值。	角色扮演的基本信息。

请求示例

GET /?RoleTrn=trn:iam::200000****:role/example-role&RoleSessionName=assumeroledemo&Action=AssumeRole&Version=2018-01-01 HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: sts.volcengineapi.com
X-Date: 20180614T131357Z
Authorization: HMAC-SHA256 Credential=AKLT4MQ/20180614/cn-north-1/sts/request, SignedHeaders=accept;content-type;host;x-date, Signature=83671ac2**8a5581f

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202104124922",
        "Action": "AssumeRole",
        "Version": "2018-01-01",
        "Service": "sts"
    },
    "Result": {
        "Credentials": {
            "CurrentTime": "2021-04-12T10:57:09+08:00",
            "ExpiredTime": "2021-04-12T11:57:09+08:00",
            "AccessKeyId": "AKTPODg0MzV**2ZDcxMDg",
            "SecretAccessKey": "TVRNNVlqRmxPR1**mRoTkdWbE1ESQ==",
            "SessionToken": "STSeyJBY2NvdW50SW******W50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MzAyMTcsIkNoYW5uZWwiOiJyZXNvdXJjZSIsIkFjY2Vzc0tleUlkIjoiQUtUUE9EZzBNelZrWlRNMVlqQXlOR05sWkdGbU0yVTNaVEl6T0RnMlpEY3hNRGciLCJTaWduZWRTZWNyZXRBY2Nlc3NLZXkiOiJHSHRuc2Q1b3BOOThUeUNrckVuMVAxTDd1ZzBXczZFMytzTktDMDJQT01lNzFMOUloNzhYaDB5VXE4Ni9JMW8reEZxTmtkK01tVUR0cjRHR0NodXJQdz09IiwiRXhwaXJlZFRpbWUiOjE2MTgxOTk4MjksIlBvbGljeVN0cmluZyI6IiIsIlNpZ25hdHVyZSI6IjdiZTEzNTU1MDM5NzcyM2VkMDQxYmVkNTIyNzU4YmMyNjQ3YzRmNzZiNmRjYTViNzVhZDUyOTMwYTg1NjE5ZGEiLCJTZXNzaW9uTmFtZSI6ImNlc2hpYXNzdW1lIn0="
        },
        "AssumedRoleUser": {
            "Trn": "trn:sts::2000000000:assumed-role/example-role/assumeroledemo",
            "AssumedRoleId": "20000:assumeroledemo"
        }
    }
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidParameter	The parameter '{{.Name}}' is invalid.	存在无效调用参数。
400	RoleNotExist	Role '{{.Role}}' does not exist.	所要扮演的角色不存在。
403	RootUserAssumeRole	Root user is forbidden to assume role.	主账号无法进行角色扮演，请使用子用户或角色进行扮演。
403	NoPermission	You have no permission for this action.	角色未信任身份进行扮演。