Help Center/ Identity and Access Management_Identity and Access Management (New Edition)/ User Guide/ Identity/ Temporary Security Credentials/ Obtaining Temporary Security Credentials
Updated on 2026-07-24 GMT+08:00
View PDF
Share

Obtaining Temporary Security Credentials

To call STS APIs, you can use the Huawei Cloud SDK. The SDK supports a wide range of programming languages and environments, including Java, Python, Go, Node.js, .NET, and PHP, and automatically handles tasks such as signing API requests, retrying requests when necessary, and processing error responses. Alternatively, you can call the STS APIs directly. For details, see the Identity and Access Management API Reference. When calling an STS API to obtain temporary security credentials, you can pass session policies and session tags. The method for passing session tags varies depending on the API operation; for details, see Passing Session Tags. The final permissions of the generated temporary security credentials are the intersection of the session policy and the identity policy of the trust agency.

The length of the session token returned by STS API operations is not fixed. It is recommended that you do not set a hard limit on its maximum length. A typical token is smaller than 4,096 bytes, but this size may change in future updates.

STS API Endpoints

STS APIs can be called using any regional endpoint. However, we recommend selecting an endpoint closest to your location to reduce latency and improve API call performance. If you cannot communicate with your primary endpoint, you can redirect your calls to endpoints in other regions 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 Using the AssumeAgency API

Before calling the AssumeAgency API, perform the following prerequisites:
  • Create an agency or trust agency, and configure which Huawei Cloud accounts can assume this agency to perform operations. For more information about trust agencies, see Trust Agency Overview.
  • Create a user, and grant the user permissions to call the STS AssumeAgency API to assume an agency or trust agency. For more information about the permissions required to call the AssumeAgency API, see Granting Permissions to Obtain Temporary Security Credentials.
  • Create a permanent access key (AK/SK) for this user to call the AssumeAgency API to obtain temporary security credentials, or use already obtained temporary security credentials to call the AssumeAgency API again to obtain new temporary security credentials. To learn how to call the AssumeAgency API, see the subsequent sections of this chapter.

After an STS AssumeAgency API request is successfully signed using a permanent access key or temporary security credentials (including temporary AK/SK and a session token) and called, the API returns new temporary security credentials. The user (or the application run by the user) can then use these temporary security credentials to access your Huawei Cloud resources.

AssumeAgency API is applicable to scenarios where an existing IAM user lacks permissions to access specific resources but still needs access. For example, a user needs to operate resources in another Huawei Cloud account. Additionally, you can use it to temporarily obtain privileged access, and you can enforce security by requiring callers to complete multi-factor authentication (MFA). When calling this API, the request must be signed with a permanent access key or temporary security credentials. You can pass the following parameters during the call:

  • (Optional) duration_seconds: validity period, in seconds, of the obtained temporary security credentials. 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.
  • (Required) agency_urn: uniform resource name (URN) of an agency or trust agency.
  • (Required) 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"
	}
}

Obtaining Temporary Security Credentials Using the AssumeAgencyWithSAML API

Before calling the AssumeAgencyWithSAML API, perform the following prerequisites:

Unlike the AssumeAgency API, the AssumeAgencyWithSAML API does not require a permanent access key or temporary security credentials to sign the request. Once the prerequisites are complete, you can call the API by passing the request body. After a successful call, the AssumeAgencyWithSAML API returns temporary security credentials, which the user (or the application the user is running) can then use to access your Huawei Cloud resources.

The AssumeAgencyWithSAML API is specifically designed to return temporary security credentials for SAML federated principals (users authenticated through an enterprise's existing identity system). Users must pass their identity information to Huawei Cloud in accordance with the SAML 2.0 standard. This API is highly practical in scenarios where an enterprise has integrated its existing identity management system with software that generates SAML assertions (such as AD FS or Shibboleth). Through this integration, the system can provide detailed information about user identities and their corresponding permissions to Huawei Cloud. You can pass the following parameters during the call:

The request body of the AssumeAgencyWithSAML API call is not protected by an encrypted signature. For this reason, we recommend using a session policy in the request body only when the request is transmitted over a trusted environment; otherwise, an attacker could use a man-in-the-middle attack to tamper with the session policy and remove its restrictions.

  • (Optional) duration_seconds: validity period, in seconds, of the obtained temporary security credentials. The value ranges from 900 to 43,200, in seconds. The default value is 3,600. The final validity period of the generated temporary security credentials is determined by duration_seconds, the SessionDuration attribute, and the SessionNotOnOrAfter attribute in the SAML response, taking the minimum of the three. This duration must also be shorter than the maximum session duration configured for the trust agency itself.
  • (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.
  • (Required) agency_urn: URN of the trust agency to switch to.
  • (Required) provider_urn: URN of the SAML IdP.
  • (Required) saml_assertion: Base64-encoded SAML authentication response provided by the SAML IdP.

The following example shows a sample request and response using the AssumeAgencyWithSAML API.

Example request 
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="
}

Example response

In addition to the agency session URN and ID, temporary security credentials, and their expiration time, the response also includes source_identity, audience, issuer, name_qualifier, subject, and subject_type. audience is retrieved from the Recipient attribute of the SubjectConfirmationData element in the SAML assertion. issuer is retrieved from the value of the Issuer element in the SAML assertion. name_qualifier is hash value calculated by concatenating the issuer value, your Huawei Cloud account ID, and the SAML provider name. For details on the calculation method, see Unique Identifiers for SAML-Based Federated Principals. When combined with the subject element, the name_qualifier uniquely identifies the SAML federated principal. subject is retrieved from the value of the NameID element under the Subject node in the SAML assertion. This typically represents a unique user identifier, such as an email address or employee ID. subject_type specifies the format of the NameID element under the Subject node. Its value can be persistent, transient, or the full Format URI used for the Subject and NameID elements in the SAML assertion. 
{
    "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"
    }
}

Obtaining Temporary Security Credentials Using the AssumeAgencyWithOIDC API

Before calling the AssumeAgencyWithOIDC API, complete the following prerequisites:
  • Create an OIDC IdP, and configure a trust relationship between the IdP and Huawei Cloud For details about OIDC IdPs, see Overview of OIDC-based Trust Agency SSO.
  • Create a trust agency for the OIDC protocol, and grant the user permission to call the STS AssumeAgencyWithOIDC API to switch to the trust agency. For details about the trust agency you need to create and the permissions required to call the AssumeAgencyWithOIDC API, see Creating a Trust Agency for an OIDC Identity Provider and Granting Permissions for Obtaining Temporary Security Credentials.
  • Obtain an OIDC token. After authenticating the user, the OIDC IdP generates an OIDC token containing the user's identity information. OIDC tokens are issued by an IdP compatible with the OIDC discovery mechanism (such as GitHub Actions or Azure DevOps).

Like AssumeAgency, the AssumeAgencyWithOIDC API does not require signing with a permanent access key or temporary security credentials. Once the prerequisites are complete, you can call the API by passing the request body. After a successful call, the AssumeAgencyWithOIDC API returns temporary security credentials, which the user (or the application the user is running) can then use to access your Huawei Cloud resources.

The AssumeAgencyWithOIDC API uses an OIDC token to return a set of temporary security credentials. The following information can be passed when calling the API:

The request body of an AssumeAgencyWithOIDC call is not protected by a cryptographic signature. For this reason, we recommend using a session policy in the request body only when the request is transmitted over a trusted environment; otherwise, an attacker could use a man-in-the-middle attack to tamper with the session policy and remove its restrictions.

  • (Optional) duration_seconds: validity period, in seconds, of the obtained temporary security credentials. Valid values range from 900 to 43,200, with the default of 3,600. This value must be less than the maximum session duration configured for the trust agency itself.
  • (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.
  • (Required) agency_urn: URN of the trust agency to switch to.
  • (Required) agency_session_name: trust agency session name. This parameter identifies the session when switching to a trust agency using an OIDC token. The administrator may require you to specify your user name in the external IdP as the session name when switching to the trust agency.
  • (Required) provider_urn: URN of the OIDC IdP.
  • (Required) id_token: OIDC token provided by the OIDC IdP, in JWT format. RSA and EC algorithms are supported.

The following example shows the request and response for calling the AssumeAgencyWithOIDC API.

Example request 
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"
}

Example response

In addition to the agency session URN and ID, temporary security credentials, and their expiration time, the response also includes source_identity, subject_from_id_token, audience, and provider. source_identity is retrieved from the source identity field configured in the OIDC token. For details on how to configure this field, see Monitoring Temporary Security Credentials. audience represents the client ID, which is typically the client identifier assigned to the application. This value is retrieved from the aud or azp claim in the OIDC token. If the azp claim is present, its value is used as the audience; otherwise, the value of the aud claim is used. subject_from_id_token is retrieved from the sub claim in the OIDC token and represents the unique user identifier returned by the OIDC IdP. provider represents the URN of the OIDC IdP. 
{
    "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"
    }
}

Using Credentials

When calling Huawei Cloud APIs using the temporary security credentials returned by the APIs above, you must include the session token in the request header via the x-security-token parameter. The overall call process is identical to using permanent AK/SK credentials, with the sole difference being the requirement of this session token, which allows Huawei Cloud to verify the validity of your temporary credentials.

Credential Management

  • Caching: Your application should cache the obtained temporary security credentials.
  • Validity Period: By default, credentials expire after 1 hour. If a specific session duration is configured, the credentials will instead expire after that duration. Note that if you specify a duration when calling the AssumeAgencyWithSAML API, or if the SessionDuration or SessionNotOnOrAfter attribute is defined in the SAML assertion, the final validity period of the temporary security credentials may be affected (see the explanation of the duration_seconds parameter for details).
  • Refreshing: It is the application's responsibility to call the API again to obtain fresh credentials before the existing ones expire.