获取临时安全凭证

在调用AssumeAgency API之前，需要执行如下前置操作：

• 创建委托或者信任委托，并配置哪些华为云账号可以切换到此委托执行操作。要了解信任委托的更多信息，请参见信任委托概述。
• 创建用户，同时授予用户调用STS服务AssumeAgency API切换委托或信任委托的权限。要了解调用AssumeAgency API所需的权限，请参见授予获取临时安全凭证的权限。
• 创建该用户的永久访问密钥用于调用AssumeAgency API获取临时安全凭证，或者使用已经获取到的临时安全凭证再次调用AssumeAgency API获取新的临时安全凭证。要了解如何调用AssumeAgency API，请参见本章节后续内容。

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"
		}
	]
}

{
	"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之前，需要执行如下前置操作：

• 创建SAML身份提供商，并配置身份提供商与华为云之间的信任关系。要了解SAML身份提供商的更多信息，请参见基于SAML协议的信任委托SSO概述。
• 创建SAML协议的信任委托，同时授予用户调用STS服务AssumeAgencyWithSAML API切换信任委托的权限。要了解调用AssumeAgencyWithSAML API所要创建的信任委托和所需权限，请参见创建 SAML 协议的信任委托和授予获取临时安全凭证的权限。
• 获取SAML断言，在验证组织用户身份后，SAML身份提供商会向华为云登录端点发送身份验证响应，其中包含一个SAML断言（Assertion）。要了解SAML断言的更多信息，请参见为身份验证响应配置SAML断言。

AssumeAgencyWithSAML API专门为SAML联邦主体（即通过组织现有身份系统完成认证的用户）返回临时安全凭证。用户必须通过SAML 2.0（安全断言标记语言）标准将身份信息传递给华为云。这一操作在以下场景中非常实用：企业已将其现有的身份管理系统与可生成SAML断言的软件（如AD FS或Shibboleth）进行了集成。通过这种集成，系统能够向华为云提供有关用户身份及相应权限的详细信息。调用时可以传递以下信息：

• 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身份验证响应。

请求示例：

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协议的联邦主体唯一标识。当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/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之前，需要执行如下前置操作：

• 创建OIDC身份提供商，并配置身份提供商与华为云之间的信任关系。要了解OIDC身份提供商的更多信息，请参见基于OIDC协议的信任委托SSO概述。
• 创建OIDC协议的信任委托，同时授予用户调用STS服务AssumeAgencyWithOIDC API切换信任委托的权限。要了解调用AssumeAgencyWithOIDC API所要创建的信任委托和所需权限，请参见创建OIDC身份提供商的信任委托和授予获取临时安全凭证的权限。
• 获取OIDC令牌，OIDC身份提供商在对用户进行身份验证后，会生成包含用户身份信息的OIDC令牌。OIDC令牌签发来源于OpenID Connect (OIDC) 发现机制兼容的身份提供商（如GitHub Actions或Azure DevOps）。

AssumeAgencyWithOIDC API通过OIDC令牌来返回一组临时安全凭证。调用时可以传递以下信息：

• 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两类算法。

请求示例：

POST https: //sts-cn-north-4.myhuaweicloud.com/v5/agencies/assume-with-oidc
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令牌中的设置的源身份字段，具体设置方式可参考监控临时安全凭证。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"
    }
}