AssumeRoleWithOIDC - 基于OIDC进行角色扮演--访问控制-火山引擎

文档中心

立即注册

访问控制

角色扮演

AssumeRoleWithOIDC - 基于OIDC进行角色扮演

基于OIDC联合认证来扮演角色获取临时安全凭证。

请求说明

该接口请求无需进行签名，建议使用 POST 方法调用，请求头 Content-Type 设置为 application/x-www-form-urlencoded，参数通过 URL 编码后以表单形式提交在请求体中。
接入地址为：sts.${RegionCode}.volcengineapi.com（例如在cn-beijing请求时接入地址为sts.cn-beijing.volcengineapi.com）
限流：每个账号 200/s

鉴权说明

该接口以传入的 OIDCToken 为凭证，根据扮演的角色的信任策略进行鉴权，需要再角色信任策略中信任身份提供商的访问。以下是一个信任某服务提供商扮演角色的信任策略示例：

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRoleWithOIDC"
            ],
            "Principal": {
                "Federated": [
                    "trn:iam::2000001234:oidc-provider/your-provider-name"
                ]
            }
        }
    ]
}

说明

角色的更多说明请参考角色管理介绍。

该接口还支持通过 Condition 条件键进一步细粒度限制权限，支持以下条件键：

条件键	说明
oidc:aud	OIDC 受众（Audience）。用于限制令牌中 aud 字段的值必须与OIDC身份提供商中配置的客户端ID（Client ID）完全一致。仅当匹配您设定的客户端ID生成的令牌满足此要求时，角色才允许被扮演，以此确保身份验证的可信性。
oidc:iss	OIDC 颁发者（Issuer）。用于限制令牌中 iss 字段的值必须与 OIDC 身份提供商中配置的颁发者 URL 完全一致。仅当受信颁发者签发的令牌满足此匹配要求时，角色才允许被扮演，以此确保身份验证的可信性。
oidc:sub	OIDC 主体（Subject）。用于进一步限制令牌中 sub 字段的值满足对应条件要求时，角色才允许被扮演。

以下是添加条件键限制后的一个信任策略示例：

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRoleWithOIDC"
            ],
            "Principal": {
                "Federated": [
                    "trn:iam::2000001234:oidc-provider/your-provider-name"
                ]
            },
            "Condition": {
                "StringEquals": {
                    "oidc:aud": "my-client-id",
                    "oidc:iss": "https://oidc.example.com",
                    "oidc:sub": "user:alice"
                }
            }
        }
    ]
}

说明

条件语法详细说明请参考 Condition（条件）说明。

请求参数

参数	类型	是否必填	示例值	描述
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`
OIDCToken	String	是	eyJraWQiOiJKQzl3eHpyaHFKMGd0****	由外部 IdP 签发的 OIDC 令牌（OIDC Token）。长度：4~65536 个字符。
Policy	String	否	{"Statement":[{"Effect":"Allow","Action":["iam:GetUser"],"Resource":["*"]}]}	角色内联策略，用于进一步限制临时凭证的权限。长度不超过2048字符。如果内联权限策略不为空，则临时凭证的实际权限为所扮演角色的权限策略与内联权限策略的交集。策略语法格式同普通的IAM策略，可参考策略语法介绍。
DurationSeconds	Integer	否	3600	临时密钥有效时长（单位：秒），最短可设为900秒，最长可设为角色最大会话时长值（在角色信息中配置），默认值为3600秒。
RoleSessionName	String	是	Bob	角色会话名称，长度2-64字符，支持英文、数字和.-_@符号。对于同一个角色，在每次扮演时可以指定不同的会话名称，从而达到区分会话的目的。该字段也会在操作审计中体现，方便从审计日志中区分不同会话的访问记录。

返回参数

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

请求示例

POST /?Action=AssumeRoleWithOIDC&Version=2018-01-01 HTTP/1.1
Host: sts.volcengineapi.com
Content-Type: application/x-www-form-urlencoded
User-Agent: curl/7.64.1

RoleTrn=trn%3Aiam%3A%3A2000012345%3Arole%2Fmy_role&OIDCToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example&Policy=%7B%22Statement%22%3A%5B%7B%22Effect%22%3A%22Allow%22%2C%22Action%22%3A%5B%22%2A%22%5D%2C%22Resource%22%3A%5B%22%2A%22%5D%7D%5D%7D&DurationSeconds=3600&RoleSessionName=Bob

返回示例

{
  "ResponseMetadata": {
    "RequestId": "202503172004180982021380116A5E29",
    "Action": "AssumeRoleWithOIDC",
    "Version": "2018-01-01",
    "Service": "sts",
    "Region": "cn-beijing"
  },
  "Result": {
    "Credentials": {
      "CurrentTime": "2021-04-12T10:57:09+08:00\n\n",
      "Expiration": "2021-04-12T11:57:09+08:00\n\n",
      "AccessKeyId": "AKTPODg0MzV**2ZDcxMDg\n\n",
      "SecretAccessKey": "TVRNNVlqRmxPR1**mRoTkdWbE1ESQ==\n\n",
      "SessionToken": "STSeyJBY2NvdW50SW******...W50a"
    },
    "OIDCTokenInfo": {
      "Subject": "KryrkIdjylZb7agUgCEf****",
      "Issuer": "https://dev-xxxxxx.****.com",
      "ClientIds": [
        "496271242565057****"
      ],
      "ExpirationTime": "2021-10-20T04:27:09Z",
      "IssuanceTime": "2021-10-20T03:27:09Z"
    },
    "AssumedRoleUser": {
      "AssumedRoleId": "5DokUfQQs",
      "Trn": "vJ"
    }
  }
}

错误码

状态码	错误码	错误信息	说明
400	InvalidOIDCToken	Invalid OIDC Token format	OIDC Token 不合法。
400	RoleNotExist	Role '{{.Role}}' does not exist.	所要扮演的角色不存在。
400	InvalidParameter	The parameter '{{.Name}}' is invalid.	存在无效调用参数。

最近更新时间：2026.01.12 16:01:18

这个页面对您有帮助吗？

有用

无用

访问控制

请求说明 #

鉴权说明 #

请求参数 #

返回参数 #

请求示例 #

返回示例 #