# 获取临时安全凭证
要调用STS API ，您可以使用华为SDK，此工具包适用于各种不同的编程语言和环境，包括Java、Python、Go、NodeJS、.NET和PHP，并负责处理各种任务，如对您的API请求进行签名、在必要时重试请求以及处理错误响应。您也可直接调用STS API，详情请参阅《统一身份认证API参考》。您可以在调用STS API获取临时安全凭证时传递会话策略及会话标签，其中会话标签根据接口的不同，其传递方式也有所不同，可参考[传递会话标签](https://support.huaweicloud.com/usermanual-iam5/iam_01_1264.html)。最终生成的临时安全凭证的权限是信任委托的身份策略与会话策略的权限交集。
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/note_3.0-zh-cn.png)
STS API操作返回的会话令牌长度不固定，建议不要限制其最大值。典型的令牌大小小于4096字节，但后续版本可能会发生变化。
#### STS API终端节点
STS API支持在任意区域终端节点进行调用，但是建议选择更靠近您的终端节点，以减少延迟，提升API调用的性能。如果您无法与原终端节点进行通信，也可选择将调用重定向到其他区域的终端节点实现容灾。如果您使用某种语言的华为云SDK，请先使用工具包的方法指定一个区域，然后再进行API调用。如果您正在手动构建HTTP API请求，则必须自行将请求发送到正确的终端节点。有关更多终端节点的信息，您可以从[地区和终端节点](https://console.huaweicloud.com/apiexplorer/#/endpoint/STS)获取。
 #### 使用AssumeAgency API获取临时安全凭证
在调用AssumeAgency API之前，需要执行如下前置操作：
- 创建委托或者信任委托，并配置哪些华为云账号可以切换到此委托执行操作。要了解信任委托的更多信息，请参见[信任委托概述](https://support.huaweicloud.com/usermanual-iam5/iam_01_0915.html)。
- 创建用户，同时授予用户调用STS服务[AssumeAgency API](https://support.huaweicloud.com/api-iam5/AssumeAgency.html)切换委托或信任委托的权限。要了解调用AssumeAgency API所需的权限，请参见[授予获取临时安全凭证的权限](https://support.huaweicloud.com/usermanual-iam5/iam_01_1240.html)。
- 创建该用户的永久访问密钥用于调用[AssumeAgency API](https://support.huaweicloud.com/api-iam5/AssumeAgency.html)获取临时安全凭证，或者使用已经获取到的临时安全凭证再次调用AssumeAgency API获取新的临时安全凭证。要了解如何调用AssumeAgency API，请参见本章节后续内容。
 
STS AssumeAgency API请求使用永久访问密钥或者临时安全凭证（包括临时AK/SK和会话令牌）签名调用成功后，会返回新的临时安全凭证，随后用户 (或用户所运行的应用程序) 可使用新的临时安全凭证访问您的华为云资源。
[AssumeAgency API](https://support.huaweicloud.com/api-iam5/AssumeAgency.html)适用于现有IAM用户没有对应资源的访问权限，但是仍然需要访问的业务场景。例如，用户需要操作其他华为云账号中资源。此外，也可使用它来暂时获得特权访问权限，安全方面可以要求调用者提供多重身份验证（MFA）。调用此API时，必须使用永久访问密钥或者临时安全凭证进行签名。调用时可以传递以下信息：
- duration_seconds（可选）：获得的临时安全凭证的有效时间（单位秒）。duration_seconds参数取值范围为\[900秒, 43200秒\]，默认值为3600秒，同时该时间需要小于信任委托本身设置的最大会话持续时间。请注意，在委托链调用时（即携带X-Security-Token的Header头）时该时间不能超过3600秒。
- external_id（可选）：外部ID。用于解决混淆代理人问题，比如您将自己的华为云资源交给专业的第三方服务商协助管理，第三方服务商会为您分配一个唯一的external_id值，您将此值配置到信任委托的信任策略中，这样可以避免第三方服务商服务的其他客户通过切换同名委托操作您的华为云资源。
- policy（可选）：会话策略。会话策略用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与会话策略的权限交集。
- policy_ids（可选）：身份策略ID列表。可以填写系统身份策略ID或者同账号下的自定义身份策略ID，同样用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与该列表中策略的权限交集。
- agency_urn（必选）：要切换的委托或者信任委托的统一资源名称URN。
- agency_session_name（必选）：委托会话名称，此参数可在不同主体切换委托或者信任委托时标识会话。管理员可能会要求您在切换委托或者信任委托时指定IAM用户名作为会话名称。
- serial_number（可选）：发起调用的IAM用户绑定的MFA设备的序列号。
- token_code（可选）：发起调用的IAM用户绑定的MFA设备上的6位数字码。
- source_identity（可选）：源身份信息。在切换委托或者信任委托并且首次设置了源身份，此值会随着security_token传递下去，后续无法删除或者修改。您可以通过源身份检索CTS日志记录来确定谁使用委托或者信任委托执行了操作。
- tags（可选）：会话标签。会话标签会保存在临时安全凭证的security_token中，用于后续鉴权。会话标签默认不会继承，即使用第一调用生成的临时安全凭证二次调用此接口生成临时安全凭证，第二次生成的临时安全凭证不包含第一次调用传递的会话标签，除非使用transitive_tag_keys参数设置可传递的标签列表。
- transitive_tag_keys（可选）：随着临时安全凭证调用链持续传递的标签键列表。
以下示例显示了调用AssumeAgency API时的请求和响应。此示例中，会切换demo委托，其中包含会话策略、会话标签、外部ID和源身份，生成的会话命名为zhangsan-session，生成的临时密钥有效期为1800s。
**请求示例**
示例中的Authorization Header头是对请求进行签名后的占位符，签名用于身份验证。建议使用签名SDK与demo创建API请求，这样做的一个好处是开发工具包将为您处理请求签名。如果您手动创建并签署API请求，请参阅[AK/SK签名认证流程](https://support.huaweicloud.com/devg-apisign/api-sign-algorithm-001.html)，以了解如何签署请求。
```
POST https://sts.cn-north-4.myhuaweicloud.com/v5/agencies/assume
Content-Type: application/json
Authorization: XXX
{
    "duration_seconds": 1800,
    "external_id": "123ABC",
    "policy": "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"obs:bucket:listBucket\"],\"Resource\":[\"obs:*:*:bucket:productionapp\"]}]}",
    "agency_urn": "iam::123456789:agency:demo",
    "agency_session_name": "zhangsan-session",
    "source_identity": "DevUser123",
    "tags": [
        {
            "key": "project",
            "value": "demo_project"
        },
        {
            "key": "cost_center",
            "value": "12345"
        }
    ]
}
```
**响应示例**
除了临时安全凭证之外，该响应还包括了源身份、委托会话的URN和临时安全凭证的到期时间。
```
{
"source_identity": "DevUser123",
"assumed_agency": {
"urn": "sts::123456789:assumed-agency:demo/zhangsan-session",
"id": "demo_agency_id:zhangsan-session"
},
"credentials": {
"access_key_id": "HSTANOXZU2UXBS55JLJ3",
"secret_access_key": "EoWCQrr...SCcw4Whkt2aXKWAr",
"security_token": "hQpjbi1XXXXXX...XXXXXbhBbA0TQ==",
"expiration": "2024-03-01T12:00:00.000Z"
}
}
```
#### 使用AssumeAgencyWithSAML API获取临时安全凭证
在调用AssumeAgencyWithSAML API之前，需要执行如下前置操作：
- 创建SAML身份提供商，并配置身份提供商与华为云之间的信任关系。要了解SAML身份提供商的更多信息，请参见[基于SAML协议的信任委托SSO概述](https://support.huaweicloud.com/usermanual-iam5/iam_01_1308.html)。
- 创建SAML协议的信任委托，同时授予用户调用STS服务AssumeAgencyWithSAML API切换信任委托的权限。要了解调用AssumeAgencyWithSAML API所要创建的信任委托和所需权限，请参见[创建 SAML 协议的信任委托](https://support.huaweicloud.com/usermanual-iam5/iam_01_1303.html)和[授予获取临时安全凭证的权限](https://support.huaweicloud.com/usermanual-iam5/iam_01_1240.html)。
- 获取SAML断言，在验证组织用户身份后，SAML身份提供商会向华为云登录端点发送身份验证响应，其中包含一个SAML断言（Assertion）。要了解SAML断言的更多信息，请参见[为身份验证响应配置SAML断言](https://support.huaweicloud.com/usermanual-iam5/iam_01_1317.html)。
 
与AssumeAgency API不同，AssumeAgencyWithSAML API无需使用永久访问密钥或者临时安全凭证签名调用。在完成前置操作后，用户传入请求体即可进行调用。在调用成功后，AssumeAgencyWithSAML API会返回临时安全凭证，随后用户 (或用户所运行的应用程序) 可使用临时安全凭证访问您的华为云资源。
AssumeAgencyWithSAML API专门为SAML联邦主体（即通过组织现有身份系统完成认证的用户）返回临时安全凭证。用户必须通过**SAML 2.0** （安全断言标记语言）标准将身份信息传递给华为云。这一操作在以下场景中非常实用：企业已将其现有的身份管理系统与可生成SAML断言的软件（如**AD FS** 或**Shibboleth** ）进行了集成。通过这种集成，系统能够向华为云提供有关用户身份及相应权限的详细信息。调用时可以传递以下信息：
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/warning_3.0-zh-cn.png)
对AssumeAgencyWithSAML的调用中的请求体是没有被加密签名保护的。因此，只有在请求通过可信环境传输时，请求体中才建议使用会话策略，否则攻击者可能会利用"中间人篡改"机制来篡改会话策略以移除限制。
- duration_seconds（可选）：获得的临时安全凭证的有效时间（单位秒）。duration_seconds参数取值范围为\[900\~43200秒\]，默认值为3600秒。最终生成的临时安全凭证有效时长受duration_seconds、SAML响应中的SessionDuration属性和SessionNotOnOrAfter属性共同控制，取三者最小值。同时该时间需要小于信任委托本身设置的最大会话持续时间。
- policy（可选）：会话策略。会话策略用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与会话策略的权限交集。
- policy_ids（可选）：身份策略ID列表。可以填写系统身份策略ID或者同账号下的自定义身份策略ID，同样用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与该列表中策略的权限交集。
- agency_urn（必选）：要切换的信任委托的统一资源名称URN。
- provider_urn（必选）：SAML身份提供商的统一资源名称URN。
- saml_assertion（必选）：由SAML身份提供商提供的**Base64**编码的SAML身份验证响应。
 
以下示例显示了调用AssumeAgencyWithSAML API时的请求和响应。
**请求示例：**
```
POST https://sts.cn-north-4.myhuaweicloud.com/v5/agencies/assume-with-saml
Content-Type: application/json
{
    "duration_seconds": 1800,
    "policy": "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"obs:bucket:listBucket\"],\"Resource\":[\"obs:*:*:bucket:productionapp\"]}]}",
    "agency_urn": "iam::123456789:agency:demo",
    "provider_urn": "iam::user_account_id:samlProvider:test",
    "saml_assertion": "PD94bWwgdmVyc...FtbDJwOlJlc3BvbnNlPgo="
}
```
**响应示例：**
除了委托会话URN和ID、临时安全凭证和其到期时间之外，该响应还包括了source_identity、audience、issuer、name_qualifier、subject和subject_type。其中，audience取自SAML断言中SubjectConfirmationData元素的Recipient属性值，issuer取自SAML断言中的Issuer元素值。name_qualifier是一个哈希值，是由"签发者（Issuer）"的值、华为云账号ID以及SAML提供商名称拼接后计算得出的哈希值，计算方式可参考[基于SAML协议的联邦主体唯一标识](https://support.huaweicloud.com/usermanual-iam5/iam_01_1308.html)。当name_qualifier与 Subject元素结合时，便可以唯一地识别该SAML联邦主体身份。subject取自SAML断言中Subject节点下的NameID元素的值，通常指用户的唯一标识符，如邮箱或工号。而subject_type用于指明 Subject节点下NameID元素的格式。其值可以是 persistent（持久性）、transient（临时性），或者是SAML断言中Subject和NameID元素所使用的完整Format URI。
```
{
    "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::123456789:assumed-agency:demo/zhangsan-session",
        "id": "demo_agency_id:zhangsan-session"
    },
    "credentials": {
        "access_key_id": "HSTANOXZU2UXBS55JLJ3",
        "secret_access_key": "EoWCQrr...SCcw4Whkt2aXKWAr",
        "security_token": "hQpjbi1XXXXXX...XXXXXbhBbA0TQ==",
        "expiration": "2024-03-01T12:00:00.000Z"
    }
}
```
#### 使用AssumeAgencyWithOIDC API获取临时安全凭证
在调用AssumeAgencyWithOIDC API之前，需要执行如下前置操作：
- 创建OIDC身份提供商，并配置身份提供商与华为云之间的信任关系。要了解OIDC身份提供商的更多信息，请参见[基于OIDC协议的信任委托SSO概述](https://support.huaweicloud.com/usermanual-iam5/iam_01_1321.html)。
- 创建OIDC协议的信任委托，同时授予用户调用STS服务AssumeAgencyWithOIDC API切换信任委托的权限。要了解调用AssumeAgencyWithOIDC API所要创建的信任委托和所需权限，请参见[创建OIDC身份提供商的信任委托](https://support.huaweicloud.com/usermanual-iam5/iam_01_1304.html)和[授予获取临时安全凭证的权限](https://support.huaweicloud.com/usermanual-iam5/iam_01_1240.html)。
- 获取OIDC令牌，OIDC身份提供商在对用户进行身份验证后，会生成包含用户身份信息的OIDC令牌。OIDC令牌签发来源于OpenID Connect (OIDC) 发现机制兼容的身份提供商（如GitHub Actions或Azure DevOps）。
 
同样，AssumeAgencyWithOIDC API无需使用永久访问密钥或者临时安全凭证签名调用。在完成前置操作后，用户传入请求体即可进行调用。在调用成功后，AssumeAgencyWithOIDC API会返回临时安全凭证，随后用户 (或用户所运行的应用程序) 可使用临时安全凭证访问您的华为云资源。
AssumeAgencyWithOIDC API通过OIDC令牌来返回一组临时安全凭证。调用时可以传递以下信息：
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/warning_3.0-zh-cn.png)
对 AssumeAgencyWithOIDC 的调用中的请求体是没有被加密签名保护的。因此，只有在请求通过可信环境传输时，请求体中才建议使用会话策略，否则攻击者可以利用"中间人篡改"机制来篡改会话策略以移除限制。
- duration_seconds（可选）：获得的临时安全凭证的有效时间（单位秒）。duration_seconds参数取值范围为\[900\~43200秒\]，默认值为3600秒，同时该时间需要小于信任委托本身设置的最大会话持续时间。
- policy（可选）：会话策略。会话策略用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与会话策略的权限交集。
- policy_ids（可选）：身份策略ID列表。可以填写系统身份策略ID或者同账号下的自定义身份策略ID，同样用于限制信任委托的身份策略中分配的权限，最终生成的临时安全凭证的权限是信任委托的身份策略与该列表中策略的权限交集。
- agency_urn（必选）：要切换的信任委托的统一资源名称URN。
- agency_session_name（必选）：信任委托会话名称，此参数可在使用OIDC令牌切换信任委托时标识会话。管理员可能会要求您在切换信任委托时指定您在外部身份提供商中的用户名作为会话名称。
- provider_urn（必选）：OIDC身份提供商的统一资源名称URN。
- id_token（必选）：由OIDC身份提供商提供的OIDC令牌，为JWT（Json Web Token）格式，支持RSA和EC两类算法。
 
以下示例显示了调用AssumeAgencyWithOIDC API时的请求和响应。
**请求示例：**
```
POST https://sts.cn-north-4.myhuaweicloud.com/v5/agencies/assume-with-saml
Content-Type: application/json
{
    "duration_seconds": 1800,
    "policy": "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"obs:bucket:listBucket\"],\"Resource\":[\"obs:*:*:bucket:productionapp\"]}]}",
    "agency_urn": "iam::123456789:agency:demo",
    "agency_session_name": "zhangsan-session",
    "provider_urn": "iam::user_account_id:oidcProvider:test",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMzQ1In0...YeJ2hFNCyRwH4DKcfBKJ782m7xmIvQ"
}
```
**响应示例：**
除了委托会话URN和ID、临时安全凭证和其到期时间之外，该响应还包括了source_identity、subject_from_id_token、audience和provider。其中，source_identity取自OIDC令牌中的设置的源身份字段，具体设置方式可参考[监控临时安全凭证](https://support.huaweicloud.com/usermanual-iam5/iam_01_1263.html)。audience取自OIDC令牌中的"aud"或"azp"字段（当"azp"存在时，取"azp"的值作为audience，否则取"aud"的值作为audience），代表客户端 ID，通常是分发给应用程序的客户端标识符。subject_from_id_token取自OIDC令牌中的"sub"字段，是OIDC身份提供商返回的唯一用户标识。provider即身份提供商的URN。
```
{
    "source_identity": "DevUser123",
    "subject_from_id_token": "sub-sample",
    "audience": "client-id-test",
    "provider": "iam::user_account_id:oidcProvider:test",
    "assumed_agency": {
        "urn": "sts::123456789:assumed-agency:demo/zhangsan-session",
        "id": "demo_agency_id:zhangsan-session"
    },
    "credentials": {
        "access_key_id": "HSTANOXZU2UXBS55JLJ3",
        "secret_access_key": "EoWCQrr...SCcw4Whkt2aXKWAr",
        "security_token": "hQpjbi1XXXXXX...XXXXXbhBbA0TQ==",
        "expiration": "2024-03-01T12:00:00.000Z"
    }
}
```
#### 使用凭证
使用以上API返回的临时安全凭证进行华为云API调用时，必须包含会话令牌，通过"x-security-token"请求头进行传递。这与使用永久AK/SK凭证调用API的过程相同，区别在于您必须包含会话令牌，以便华为云验证该临时安全凭证的有效性。
**凭证管理：**
- **缓存：** 您的应用程序应当缓存获取到的临时安全凭证。
- **有效期：** 默认情况下，凭证在**1小时**后过期。特别地，如果您设置了会话时长，凭证会在您设置的时间后过期。注意，如果您在调用AssumeAgencyWithSAML API时设置了有效时长或者在SAML断言中设置了SessionDuration属性或SessionNotOnOrAfter属性，临时安全凭证最终有效期会受到影响，详见duration_seconds参数解释。
- **刷新：** 由应用程序自行负责在旧凭证过期前再次调用接口以获取新凭证。