# 通过使用SAML协议SSO的信任委托获取临时安全凭证 - AssumeAgencyWithSAML #### 功能介绍 为通过 SAML 身份验证响应（SAML Authentication Response）验证的用户返回一组临时安全凭证。此操作提供了一种机制，可以让外部的 SAML 身份提供商使用信任委托的临时安全凭证华为云访问，而无需使用 IAM 用户的凭证。 **会话持续时间：** 默认情况下，通过 AssumeAgencyWithSAML 创建的临时安全凭证有效期为一小时。您可以使用可选的 duration_seconds 参数或者 SAML 身份验证响应中 SessionNotOnOrAfter 值和 SessionDuration 值来指定会话的持续时间，最终的会话持续时间以三者中较短的一个为准，且会话的持续时间不能超过委托设置的最大会话时长限制。duration_seconds 取值范围是从 900 秒（15 分钟）到该信任委托设置的最大会话持续时长，最大会话持续时长的取值范围可以从 1 小时到 12 小时。注意：委托链会将您的会话持续时间限制为最多一小时，当您使用 AssumeAgency API 操作来进行委托链的切换时，如果您提供了大于一小时的 duration_seconds 参数值，该操作将会失败。 **权限：** 调用 AssumeAgencyWithSAML 不需要使用华为云凭证。调用者的身份是通过使用您上传的 SAML 提供商元数据文档中的密钥进行验证的。 您可以使用 policy 和 policy_ids 参数传递自定义策略和已有的身份策略来限制本次会话获得的临时安全凭证的权限范围，最终获得临时安全凭证的权限是 policy 和 policy_ids 与信任委托身上附加的身份策略的交集。 **标签：** 在信任委托的信任策略中添加了 sts::tagSession 授权项时，您可以配置您的身份提供商，将属性作为会话标签 (Session Tags) 传递到 SAML 断言中。每个会话标签由一个键（Key）和一个值（Value）组成。您最多可以传递 20 个会话标签。纯文本形式的会话标签键不得超过 128 个字符，值不得超过 255 个字符。您也可以传递与信任委托身上标签同名的会话标签，此时会话标签会覆盖具有相同键的信任委托标签。您可以将会话标签设置为可传递的 (Transitive)，可传递的会话标签在角色链期间会持续保留，有关更多信息，请参阅 IAM 用户指南中的[传递会话标签](https://support.huaweicloud.com/usermanual-iam5/iam_01_1264.html)。 **SAML 配置：** 在您的应用程序调用 AssumeAgencyWithSAML 之前，您必须使用您的账号在 IAM 中创建 SAML 提供商和信任委托，并在信任委托的信任策略中指定该 SAML 提供商，然后还需要配置您的 SAML 身份提供商以发布 IAM 所需的声明 (Claims)。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/STS/doc?api=AssumeAgencyWithSAML&version=v1)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-iam5/iam_02_1125.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | sts:agencies:assumeWithSAML | Write | agency \* | g:ResourceTag/\ | - | - sts::tagSession - sts::setSourceIdentity | | sts:agencies:assumeWithSAML | Write | - | - saml:namequalifier - saml:sub - saml:sub_type - saml:aud - saml:iss - g:TagKeys - g:RequestTag/\ - sts:TransitiveTagKeys - sts:SourceIdentity - sts:AgencySessionName | - | - sts::tagSession - sts::setSourceIdentity | #### URI POST /v5/agencies/assume-with-saml #### 请求参数 表1请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | duration_seconds | 否 | Integer | **参数解释**： 获得的临时安全凭证的有效时间（单位：秒）。 **约束限制**： 请注意，该时间需要小于信任委托本身设置的最大会话持续时间。同时最终的会话持续时间以duration_seconds、 SAML身份验证响应中SessionNotOnOrAfter值和SessionDuration值三者中较短的一个为准。 **取值范围**： 取值范围为\[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 | **参数解释**： SAML提供商的URN，在IAM新版控制台的「身份提供商」页面中获取。 **约束限制**： 不涉及。 **取值范围**： 长度最大为1500个字符。 **默认取值**： 不涉及。 | | agency_urn | 是 | String | **参数解释**： 目标信任委托的URN，在IAM新版控制台的「委托」页面中获取。 **约束限制**： 不涉及。 **取值范围**： 长度最大为1500个字符。 **默认取值**： 不涉及。 | | saml_assertion | 是 | String | **参数解释**： 由SAML身份提供商提供的Base64编码的SAML身份验证响应。 **约束限制**： 不涉及。 **取值范围**： 长度为4到100000个字符，只允许大小写字母、数字、"+"、"/"，末尾可跟0到2个"="。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表2响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | source_identity | String | **参数解释**： SAML断言中SourceIdentity属性值所申明的身份。 | | assumed_agency | [AssumedAgencyWithFederationDto] object | **参数解释**： 信任委托会话信息。 **取值范围**： 不涉及。 | | credentials | [CredentialsDto] object | **参数解释**： 生成的临时安全凭证。 **取值范围**： 不涉及。 | | audience | String | **参数解释**： SAML断言中SubjectConfirmationData元素的Recipient属性值。 | | issuer | String | **参数解释**： SAML断言中Issuer元素的值。 | | name_qualifier | String | **参数解释**： 以下三部分的哈希值：issuer、华为云账号的Account ID以及IAM中SAML提供商的名称（URN的最后一部分）。name_qualifier和subject的组合可用于唯一标识用户。下面的伪代码展示了哈希值的计算方式：BASE64 ( SHA1 ( "https://example.com/saml" + "8c1eef3a241945f69c3d3axxxxxxxxxx" + "/MySAMLIdPName" ) ) | | subject | String | **参数解释**： SAML断言中Subject元素的NameID元素的值。 | | subject_type | String | **参数解释**： NameID的格式，由SAML断言中NameID元素的Format属性定义。格式的典型示例是transient（临时）或persistent（持久）。 如果该格式包含前缀urn:oasis:names:tc:SAML:2.0:nameid-format，该前缀将被移除。例如，urn:oasis:names:tc:SAML:2.0:nameid-format:transient将作为transient返回。如果格式包含任何其他前缀，则直接返回该格式而不作任何修改。 | 表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与SAML断言获取临时安全凭证。 ``` POST https://{endpoint}/v5/agencies/assume-with-saml { "duration_seconds" : 3600, "policy" : "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"obs:bucket:listBucket\"],\"Resource\":[\"obs:::bucket:productionapp\"]}]}", "agency_urn" : "iam::27680d67da6b47eb82d00a1a118be145:agency:Y0yfCQYJGO", "provider_urn" : "iam::27680d67da6b47eb82d00a1a118be145:samlProvider:test", "saml_assertion" : "PD94bWwgdmVyc...FtbDJwOlJlc3BvbnNlPgo=" } ``` #### 响应示例 **状态码：200** ``` { "source_identity" : "DevUser123", "audience" : "https://auth.huaweicloud.com/authui/v5/saml", "issuer" : "https://demo-idp.com", "name_qualifier" : "OB60V...5Ke5EnHU=", "subject" : "demo@example.com", "subject_type" : "persistent", "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)。