Obtaining Temporary Security Credentials

STS API Endpoints

You can call STS APIs using any endpoints in any regions. You are advised to select an endpoint closer to you to reduce latency and improve the API calling performance. If you can no longer communicate with the original endpoint, you can redirect calls to an alternative region endpoint for disaster recovery. If you are using one of the Huawei Cloud SDKs, then use that SDK method to specify a region before you make the API call. If you manually construct HTTP API requests, then you must direct the request to the correct endpoint yourself. You can obtain more information about endpoints from Regions and Endpoints.

Obtaining Temporary Security Credentials Through an Agency or Trust Agency

The AssumeAgency API can be used to allow existing IAM users to access resources that they do not have access to. For example, the user might need to access resources in another Huawei Cloud account. In addition, the AssumeAgency API can be used to temporarily obtain privileged access and provide Multi-Factor Authentication (MFA). When calling this API, you must use permanent access keys or temporary security credentials to sign requests. When making this call, you can pass the following information:

• (Optional) duration_seconds: validity period, in seconds, of the obtained temporary security credential. The value ranges from 900 to 43200 seconds. The default value is 3600 seconds. The value must be less than the maximum session duration set for the trust agency. It cannot exceed 3600 seconds when the agency chain is called (the header contains X-Security-Token).
• (Optional) external_id: external ID, which helps prevent confused deputy issues. For example, if you hand over your Huawei Cloud resources to a professional third-party service provider for management, the third-party service provider will assign a unique external_id value to you. You can configure this value in the identity policy of the trust agency to prevent other customers of the third-party service provider from operating your Huawei Cloud resources by assuming an agency with the same name.
• (Optional) policy: session policies, which limit the permissions defined in the trust agency's identity policies. The permissions of the resulting temporary security credentials are the intersection of the trust agency's identity policies and the session policies.
• (Optional) policy_ids: identity policy IDs, which can be system-defined identity policy IDs or the custom identity policy IDs of the same account. This parameter is used to limit the permissions defined in the trust agency's identity policies. The permissions of the resulting temporary security credentials are the intersection of the trust agency's identity policies and the policies in this list.
• agency_urn: uniform resource name (URN) of an agency or trust agency.
• agency_session_name: assumed-agency session name, which can be used to identify the session when different principals switch an agency or trust agency. The administrator may ask you to specify the IAM username as the session name when you switch an agency or trust agency.
• (Optional) serial_number: serial number of the MFA device added to the IAM user who initiates the call.
• (Optional) token_code: 6-digit code generated by the MFA device added to the IAM user who initiates the call.
• (Optional) source_identity: source identity information. If you set a source identity when switching an agency or trust agency, its value will be transmitted along with the security_token and cannot be deleted or modified. You can search by source identity in Cloud Trace Service (CTS) logs to know who have assumed the agency or trust agency.
• (Optional) tags: session tags, which are stored in the session token security_token of temporary security credentials for subsequent authentication. The session tags are not inherited by default. This means when the temporary security credentials generated during the first call are used to generate new temporary security credentials, the newly generated temporary security credentials do not contain the session tags transferred during the first call, unless transitive_tag_keys is used to specify a tag list.
• (Optional) transitive_tag_keys: Tag key list that is transmitted along with the temporary security credential in the call chain.

The following example shows a sample request and response using the AssumeAgency API. This example request assumes the demo agency with the included session policy, session tags, external ID, and source identity. The generated session is named zhangsan-session, and the validity period of the generated temporary security credentials is 1800s.

Example Request

In the example, the Authorization header is a placeholder for the signed request, which is used for identity authentication. You are advised to use the signing SDK and demo to create API requests. In this way, the SDK will handle signing request for you. If you must create and sign API requests manually, see AK/SK Authentication Process to learn how to sign a request.

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

Example Response

In addition to the temporary security credentials, the response also includes the source identity, the URN of the assumed-agency session, and the expiration time of the temporary security credentials.

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