# 通过委托或者信任委托获取临时安全凭证 - AssumeAgency #### 功能介绍 通过委托或者信任委托获取临时安全凭证，临时安全凭证可用于对云资源发起访问。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/STS/doc?api=AssumeAgency&version=v1)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-iam5/iam_02_1125.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | sts:agencies:assume | Write | agency \* | g:ResourceTag/\ | - | - sts::tagSession - sts::setSourceIdentity | | sts:agencies:assume | Write | - | - sts:ExternalId - sts:SourceIdentity - sts:TransitiveTagKeys - sts:AgencySessionName - g:RequestTag/\ - g:TagKeys - g:SourceAccount - g:SourceUrn - saml:namequalifier - saml:sub - saml:sub_type | - | - sts::tagSession - sts::setSourceIdentity | #### URI POST /v5/agencies/assume #### 请求参数 表1请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Security-Token | 否 | String | **参数解释**： 临时安全凭证的security_token字段。 **约束限制**： 通过临时安全凭证调用接口时，需要提供"X-Security-Token"Http头。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | duration_seconds | 否 | Integer | **参数解释**： 获得的临时安全凭证的有效时间（单位：秒）。 **约束限制**： 请注意，该时间需要小于委托本身设置的最大会话持续时间（在IAM控制台「委托」页面中获取），同时在携带X-Security-Token的Header头时该时间不能超过3600秒。 **取值范围**： 取值范围为\[900,43200\]。 **默认取值**： 默认值为3600。 | | external_id | 否 | String | **参数解释**： 外部ID，防止混淆代理人问题。 **约束限制**： 不涉及。 **取值范围**： 长度为2到1224个字符，只允许大小写字母、数字、"_"、"+"、"="、","、"."、"@"、":"、"/"、"-"。 **默认取值**： 不涉及。 | | policy | 否 | String | **参数解释**： 自定义策略，用于进一步限制临时安全凭证的权限范围。[参考链接](https://support.huaweicloud.com/usermanual-iam5/iam_01_1291.html)。 **约束限制**： 本次会话获得的临时安全凭证的权限范围不会超过该自定义策略指定的权限。 **取值范围**： 长度为2到4096个字符。 **默认取值**： 不涉及。 | | policy_ids | 否 | Array of strings | **参数解释**： 预置策略列表，限制本次会话获得的临时安全凭证的权限范围不会超过该预置策略指定的权限。 每个元素为预置策略的标识ID，长度限制为1到64个字符，只允许大小写字母、数字、"_"、"-"，且至少包含一个字符。 **约束限制**： 该数组允许的元素个数最多为20。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | agency_urn | 是 | String | **参数解释**： 目标委托的URN，在IAM控制台的「委托」页面中获取。 **约束限制**： 不涉及。 **取值范围**： 长度最多为1500个字符。格式为5段，用":"分隔，各段允许大小写字母、数字、"+"、"/"、"="、"-"、"_"（第2段还额外允许 "\*"），长度限制为：第1段至少1位，第2段0\~255位，第3段1\~64位，第4段1\~64位，第5段至少1位（任意字符）。 **默认取值**： 不涉及。 | | agency_session_name | 是 | String | **参数解释**： 委托会话的会话名。 **约束限制**： 不涉及。 **取值范围**： 长度为2到128个字符，只允许大小写字母、数字、"_"、"+"、"="、","、"."、"@"、"-"。 **默认取值**： 不涉及。 | | serial_number | 否 | String | **参数解释**： 调用者绑定的MFA设备的序列号。在IAM控制台-\>「用户」-\>「安全设置」-\>「多因素认证设备」中获取。 **约束限制**： 不涉及。 **取值范围**： 长度为9到256个字符，只允许大小写字母、数字、"_"、"+"、"="、"/"、":"、","、"."、"@"、"-"。 **默认取值**： 不涉及。 | | token_code | 否 | String | **参数解释**： 调用者绑定的MFA设备上的6位纯数字。 **约束限制**： 只允许6位数字。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | source_identity | 否 | String | **参数解释**： 调用链里最初调用者所声明的身份。 **约束限制**： 不涉及。 **取值范围**： 长度为2到64个字符，只允许大小写字母、数字、"_"、"+"、"="、","、"."、"@"、"-"。 **默认取值**： 不涉及。 | | tags | 否 | Array of [TagDto] objects | **参数解释**： 自定义标签列表。 **约束限制**： 该数组允许的元素个数最多为20。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | transitive_tag_keys | 否 | Array of strings | **参数解释**： 随着临时安全凭证调用链持续透传的标签键列表。 **约束限制**： 该数组允许的元素个数最多为20。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | provided_contexts | 否 | Array of [ProvidedContextDto] objects | **参数解释**： 预先获取的可信上下文断言列表，格式为数组。 **约束限制**： 该数组允许的元素个数为1到5。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表3TagDto | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释**： 标签键。 **约束限制**： 不涉及。 **取值范围**： 长度为1到128个字符。只允许大小写字母、数字、空格、"_"、"."、":"、"="、"+"、"-"、"@"、"/"，且不能以 "_sys_" 开头。 **默认取值**： 不涉及。 | | value | 是 | String | **参数解释**： 标签值。 **约束限制**： 不涉及。 **取值范围**： 长度为0到255个字符。只允许大小写字母、数字、空格、"_"、"."、":"、"/"、"="、"+"、"-"、"@"。取值可以为空字符串，不可以为null。 **默认取值**： 不涉及。 | 表4ProvidedContextDto | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | context_provider_urn | 是 | String | **参数解释**： 生成可信上下文断言的提供者的URN。 **约束限制**： 长度最多为1500个字符。格式为5段，用":"分隔，各段允许大小写字母、数字、"+"、"/"、"="、"-"、"_"（第2段还额外允许 "\*"），长度限制为：第1段至少1位，第2段0\~255位，第3段1\~64位，第4段1\~64位，第5段至少1位（任意字符）。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | context_assertion | 是 | String | **参数解释**： 经过签名和加密的可信上下文断言。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | source_identity | String | **参数解释**： 调用链里最初调用者所声明的身份。 **取值范围**： 不涉及。 | | assumed_agency | [AssumedAgencyDto] object | **参数解释**： 委托会话或信任委托会话信息。 **取值范围**： 不涉及。 | | credentials | [CredentialsDto] object | **参数解释**： 生成的临时安全凭证。 **取值范围**： 不涉及。 | 表6AssumedAgencyDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | urn | String | **参数解释**： 委托会话或信任委托会话的URN。 **取值范围**： 不涉及。 | | id | String | **参数解释**： 委托会话或信任委托会话的唯一标识，包含了委托ID和委托会话名称信息。 **取值范围**： 不涉及。 | 表7CredentialsDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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** 表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)。 **取值范围**： 不涉及。 | **状态码：403** 表9响应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** 表10响应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** 表11响应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获取临时安全凭证。 ``` POST https://{endpoint}/v5/agencies/assume { "duration_seconds" : 3600, "agency_urn" : "iam::27680d67da6b47eb82d00a1a118be145:agency:Y0yfCQYJGO", "agency_session_name" : "session1" } ``` #### 响应示例 **状态码：200** ``` { "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)。