# 通过使用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)，可传递的会话标签在角色链期间会持续保留，有关更多信息，请参阅 IAM 用户指南中的[传递会话标签](https://support.huaweicloud.com/usermanual-iam5/iam_01_1264.html)。 **身份：** 在您的应用程序可以调用 AssumeAgencyWithOIDC 之前，您必须使用您的账号在 IAM 中创建 OIDC 提供商和信任委托，并在信任委托的信任策略中指定该 OIDC 提供商，然后还需要配置您的 OIDC 身份提供商以颁发 IAM 所需的 ID Token。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/STS/doc?api=AssumeAgencyWithOIDC&version=v1)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-iam5/iam_02_1125.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | sts:agencies:assumeWithOIDC | Write | agency \* | g:ResourceTag/\ | - | - sts::tagSession - sts::setSourceIdentity | | sts:agencies:assumeWithOIDC | Write | - | - oidc:amr - oidc:aud - oidc:sub - oidc:iss - g:TagKeys - g:RequestTag/\ - sts:TransitiveTagKeys - sts:SourceIdentity - sts:AgencySessionName | - | - sts::tagSession - sts::setSourceIdentity | #### URI POST /v5/agencies/assume-with-oidc #### 请求参数 表1请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | duration_seconds | 否 | Integer | **参数解释**： 获得的临时安全凭证的有效时间（单位：秒）。 **约束限制**： 请注意，该时间需要小于委托本身设置的最大会话持续时间，同时在携带X-Security-Token的Header头时该时间不能超过3600秒。 **取值范围**： 取值范围为\[900,43200\]。 **默认取值**： 默认值为3600。 | | policy | 否 | String | **参数解释**： 自定义策略，用于进一步限制临时安全凭证的权限范围。[参考链接](https://support.huaweicloud.com/usermanual-iam5/iam_01_1291.html)。 **约束限制**： 本次会话获得的临时安全凭证的权限范围不会超过自定义策略指定的权限。 **取值范围**： 长度为2到4096个字符。 **默认取值**： 不涉及。 | | policy_ids | 否 | Array of strings | **参数解释**： 预置策略列表，限制本次会话获得的临时安全凭证的权限范围不会超过该预置策略指定的权限。 每个元素为预置策略的标识ID，长度限制为1到64个字符，只允许大小写字母、数字、"_"、"-"，且至少包含一个字符。 **约束限制**： 该数组允许的元素个数最多为20。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | provider_urn | 是 | String | **参数解释**： OIDC提供商的URN，在IAM新版控制台的「身份提供商」页面中获取。 **约束限制**： 不涉及。 **取值范围**： 长度最多为1500个字符。格式为5段，用":"分隔，各段允许大小写字母、数字、"+"、"/"、"="、"-"、"_"（第2段还额外允许 "\*"），长度限制为：第1段至少1位，第2段0\~255位，第3段1\~64位，第4段1\~64位，第5段至少1位（任意字符）。 **默认取值**： 不涉及。 | | agency_urn | 是 | String | **参数解释**： 目标信任委托的URN，在IAM新版控制台的「委托」页面中获取。 **约束限制**： 不涉及。 **取值范围**： 长度最多为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)声明的值。 **取值范围**： 不涉及。 | 表3AssumedAgencyWithFederationDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | urn | String | **参数解释**： 信任委托会话的URN。 **取值范围**： 不涉及。 | | id | String | **参数解释**： 信任委托会话的唯一标识，包含了信任委托ID和信任委托会话名称信息。 **取值范围**： 不涉及。 | 表4CredentialsDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | access_key_id | String | **参数解释**： 临时安全凭证的AK。 **取值范围**： 不涉及。 | | expiration | String | **参数解释**： 临时安全凭证的失效时间。ISO 8601 标准的 UTC 时间，例如：2026-08-21T17:00:01.999Z。 **取值范围**： 不涉及。 | | secret_access_key | String | **参数解释**： 临时安全凭证的SK。 **取值范围**： 不涉及。 | | security_token | String | **参数解释**： 临时安全凭证的security_token。 **取值范围**： 不涉及。 | **状态码：400** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码，请参见[错误码](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 格式为STS5.XXXX，例如 STS5.1001。 | | error_msg | String | **参数解释**： 错误信息，请参见[错误信息](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 不涉及。 | **状态码：403** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码， 请参见[错误码](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 格式为STS5.XXXX， 例如 STS5.1001。 | | error_msg | String | **参数解释**： 错误信息， 请参见[错误信息](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 不涉及。 | | encoded_authorization_message | String | **参数解释**： 认证失败时返回的加密详细信息，用于定位认证问题。 可以通过STS5解密接口进行解密，[接口链接](https://support.huaweicloud.com/api-iam5/DecodeAuthorizationMessage.html)。 **取值范围**： 不涉及。 | **状态码：404** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码，请参见[错误码](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 格式为STS5.XXXX，例如 STS5.1001。 | | error_msg | String | **参数解释**： 错误信息，请参见[错误信息](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 不涉及。 | **状态码：500** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码，请参见[错误码](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 格式为STS5.XXXX，例如 STS5.1001。 | | error_msg | String | **参数解释**： 错误信息，请参见[错误信息](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。 **取值范围**： 不涉及。 | #### 请求示例 通过账号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 | 服务端异常。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-iam5/ErrorCode.html)。