文档首页/ 统一身份认证服务 IAM_统一身份认证服务（新版）/ API参考/ API/ STS/ 临时安全凭证/ 通过使用OIDC协议SSO的信任委托获取临时安全凭证 - AssumeAgencyWithOIDC
更新时间：2026-06-16 GMT+08:00
查看PDF
分享

通过使用OIDC协议SSO的信任委托获取临时安全凭证 - AssumeAgencyWithOIDC

功能介绍

为通过 OIDC 身份提供商令牌验证的用户返回一组临时安全凭证。此操作提供了一种机制，可以让外部的任何兼容 OIDC 身份提供商使用信任委托的临时安全凭证华为云访问，而无需使用 IAM 用户的凭证。

会话持续时间：

默认情况下，通过 AssumeAgencyWithOIDC 创建的临时安全凭证有效期为一小时。您可以使用可选的 duration_seconds 参数来指定会话的持续时间，duration_seconds 取值范围是从 900 秒（15 分钟）到该信任委托设置的最大会话持续时长，最大会话持续时长的取值范围可以从 1 小时到 12 小时。注意：委托链会将您的会话持续时间限制为最多一小时，当您使用 AssumeAgency API 操作来进行委托链的切换时，如果您提供了大于一小时的 duration_seconds 参数值，该操作将会失败。

权限：

调用 AssumeAgencyWithOIDC 不需要使用华为云凭证。调用者的身份是通过使用您 JWKS 端点中的公钥进行验证的。

您可以使用 policy 和 policy_ids 参数传递自定义策略和已有的身份策略来限制本次会话获得的临时安全凭证的权限范围，最终获得临时安全凭证的权限是 policy 和 policy_ids 与信任委托身上附加的身份策略的交集。

标签：

在信任委托的信任策略中添加了 sts::tagSession 授权项时，您可以配置您的身份提供商，将属性作为会话标签传递到您的 ID Token 中。每个会话标签由一个键（Key）和一个值（Value）组成。您最多可以传递 20 个会话标签。纯文本形式的会话标签键不得超过 128 个字符，值不得超过 255 个字符。您也可以传递与信任委托身上标签同名的会话标签，此时会话标签会覆盖具有相同键的信任委托标签。您可以将会话标签设置为可传递的 (Transitive)，可传递的会话标签在角色链期间会持续保留。

身份：

在您的应用程序可以调用 AssumeAgencyWithOIDC 之前，您必须使用您的账号在 IAM 中创建 OIDC 提供商和信任委托，并在信任委托的信任策略中指定该 OIDC 提供商，然后还需要配置您的 OIDC 身份提供商以颁发 IAM 所需的 ID Token。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

sts:agencies:assumeWithOIDC

Write

agency *

g:ResourceTag/<tag-key>

-
  • sts::tagSession
  • sts::setSourceIdentity

-

  • oidc:amr

  • oidc:aud

  • oidc:sub

  • oidc:iss

  • g:TagKeys

  • g:RequestTag/<tag-key>

  • sts:TransitiveTagKeys

  • sts:SourceIdentity

  • sts:AgencySessionName

URI

POST /v5/agencies/assume-with-oidc

请求参数

表1 请求Body参数

参数

是否必选

参数类型

描述

duration_seconds

否

Integer

参数解释：

获得的临时安全凭证的有效时间（单位：秒）。

约束限制：

请注意，该时间需要小于委托本身设置的最大会话持续时间，同时在携带X-Security-Token的Header头时该时间不能超过3600秒。

取值范围：

取值范围为[900,43200]。

默认取值：

默认值为3600。

policy

否

String

参数解释：

自定义策略，参考链接。

约束限制：

本次会话获得的临时安全凭证的权限范围不会超过该自定义策略指定的权限。

长度范围为[2,2048]。

取值范围：

不涉及。

默认取值：

不涉及。

policy_ids

否

Array of strings

参数解释：

预置策略列表，限制本次会话获得的临时安全凭证的权限范围不会超过该预置策略指定的权限。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

provider_urn

是

String

参数解释：

OIDC提供商的URN。

约束限制：

长度范围为[0,1500]。

取值范围：

不涉及。

默认取值：

不涉及。

agency_urn

是

String

参数解释：

目标信任委托的URN。

约束限制：

长度范围为[0,1500]。

取值范围：

不涉及。

默认取值：

不涉及。

agency_session_name

是

String

参数解释：

信任委托会话的会话名。

约束限制：

长度范围为[2,128]。

取值范围：

不涉及。

默认取值：

不涉及。

id_token

是

String

参数解释：

由身份提供商提供的OIDC令牌。

约束限制：

长度范围为[4,20000]。

取值范围：

不涉及。

默认取值：

不涉及。

响应参数

状态码：200

表2 响应Body参数

参数

参数类型

描述

source_identity

String

参数解释：

身份提供商返回的OIDC令牌中所申明的身份。

取值范围：

不涉及。

assumed_agency

AssumedAgencyWithFederationDto object

参数解释：

信任委托会话信息。

取值范围：

不涉及。

credentials

CredentialsDto object

参数解释：

生成的临时安全凭证。

取值范围：

不涉及。

audience

String

参数解释：

OIDC令牌的预期受众（也称为客户端ID），通常是分发给应用程序的客户端标识符。

取值范围：

不涉及。

provider

String

参数解释：

身份提供商的URN。

取值范围：

不涉及。

subject_from_id_token

String

参数解释：

由身份提供商返回的唯一用户标识符，即OIDC令牌中的sub(Subject)声明的值。

取值范围：

不涉及。
表3 AssumedAgencyWithFederationDto

参数

参数类型

描述

urn

String

参数解释：

信任委托会话的URN。

取值范围：

不涉及。

id

String

参数解释：

信任委托会话的唯一标识，包含了信任委托ID和信任委托会话名称信息。

取值范围：

不涉及。
表4 CredentialsDto

参数

参数类型

描述

access_key_id

String

参数解释：

临时安全凭证的AK。

取值范围：

不涉及。

expiration

String

参数解释：

临时安全凭证的失效时间。

取值范围：

不涉及。

secret_access_key

String

参数解释：

临时安全凭证的SK。

取值范围：

不涉及。

security_token

String

参数解释：

临时安全凭证的security_token。

取值范围：

不涉及。

状态码：400

表5 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

状态码：403

表6 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码， 请参见错误码。

取值范围：

格式为STS5.XXXX， 例如 STS5.1001。

error_msg

String

参数解释：

错误信息， 请参见错误信息。

取值范围：

不涉及。

encoded_authorization_message

String

参数解释：

认证失败时返回的加密详细信息，用于定位认证问题。 可以通过STS5解密接口进行解密，接口链接。

取值范围：

不涉及。

状态码：404

表7 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

状态码：500

表8 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

请求示例

通过账号27680d67da6b47eb82d00a1a118be145下的信任委托Y0yfCQYJGO与ID Token获取临时安全凭证。

POST https://{endpoint}/v5/agencies/assume-with-oidc

{
  "duration_seconds" : 3600,
  "policy" : "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"obs:bucket:listBucket\",\"Resource\":\"obs:*:*:bucket:productionapp\"}]}",
  "agency_urn" : "iam::27680d67da6b47eb82d00a1a118be145:agency:Y0yfCQYJGO",
  "agency_session_name" : "session1",
  "provider_urn" : "iam::27680d67da6b47eb82d00a1a118be145:oidcProvider:test",
  "id_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMzQ1In0...YeJ2hFNCyRwH4DKcfBKJ782m7xmIvQ"
}

响应示例

状态码：200

请求成功。

{
  "source_identity" : "DevUser123",
  "subject_from_id_token" : "sub-sample",
  "audience" : "client-id-test",
  "provider" : "iam::{account_id}:oidcProvider:test",
  "assumed_agency" : {
    "urn" : "sts::{account_id}::assumed-agency:{agency_name}/{agency_session_name}",
    "id" : "{agency_id}:{agency_session_name}"
  },
  "credentials" : {
    "access_key_id" : "HSTANO...XBS55JLJ3",
    "secret_access_key" : "EoWCQrr...SCcw4Whkt2aXKWAr",
    "security_token" : "hQpjbi1XXXXXX...XXXXXKbhBbA0TQ==",
    "expiration" : "2022-09-07T03:27:51.158Z"
  }
}

状态码

状态码

描述

200

请求成功。

400

请求体异常。

403

没有操作权限。

404

未找到对应资源。

500

服务端异常。

错误码

请参见错误码。

父主题： 临时安全凭证

相关文档