Help Center/ Identity and Access Management_Identity and Access Management (New Edition)/ API Reference/ API/ STS/ Temporary security credentials/ Obtaining a Temporary Security Credential Through the SAML SSO Trust Agency
Updated on 2026-07-22 GMT+08:00
View PDF
Share

Obtaining a Temporary Security Credential Through the SAML SSO Trust Agency

Function

A set of temporary security credentials returned for users who have passed SAML authentication response. This operation provides a mechanism that allows any external SAML identity provider to access Huawei Cloud using the temporary security credentials of a trust agency, without using the credentials of an IAM user.

Session duration:

By default, the temporary security credentials created using AssumeAgencyWithSAML are valid for one hour. The final session duration is determined as the shortest among the optional duration_seconds parameter, the value of SessionNotOnOrAfter in the SAML authentication response, and the value of SessionDuration . The session duration cannot exceed the maximum session duration set for the agency. The value of duration_seconds ranges from 900 seconds (15 minutes) to the maximum session duration set for the trust agency. The maximum session duration ranges from 1 hour to 12 hours. Note: The agency chain limits your session duration to a maximum of one hour. When you use the AssumeAgency API to switch the agency chain, if you provide a value of duration_seconds greater than one hour, the operation will fail.

Permission:

You do not need to use a Huawei Cloud credential to call AssumeAgencyWithSAML. The identity of the caller is verified using the key in the SAML provider metadata document you uploaded.

You can use the policy and policy_ids parameters to pass custom policies and existing identity policies to limit the permissions of the temporary security credentials obtained in this session. The final permissions of the temporary security credentials are the intersection of the policies specified by policy and policy_ids and the identity policies attached to the trust agency.

Tag:

If the sts::tagSession action is added to the trust policy of a trust agency, you can configure your identity provider to pass attributes as session tags to the SAML assertion. Each session tag consists of a key and a value. You can pass up to 20 session tags. A session tag key in plain text format can contain a maximum of 128 characters, and a value can contain a maximum of 255 characters. You can also pass session tags with the same names as the tags on the trust agency. In this case, the session tags will overwrite the trust agency tags with the same keys. You can set the session tag to transitive. The transitive session tag is retained during the role chain.

SAML configuration:

Before your application can call AssumeAgencyWithSAML, you must create a SAML provider and a trust agency in IAM using your account, specify the SAML provider in the trust policy of the trust agency, and configure your SAML identity provider to issue the claims required by IAM.

Authorization Information

Each account root user has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

sts:agencies:assumeWithSAML

Write

agency *

g:ResourceTag/<tag-key>

-
  • sts::tagSession
  • sts::setSourceIdentity

-

  • saml:namequalifier

  • saml:sub

  • saml:sub_type

  • saml:aud

  • saml:iss

  • g:TagKeys

  • g:RequestTag/<tag-key>

  • sts:TransitiveTagKeys

  • sts:SourceIdentity

  • sts:AgencySessionName

URI

POST /v5/agencies/assume-with-saml

Request Parameters

Table 1 Request body parameters

Parameter

Mandatory

Type

Description

duration_seconds

No

Integer

Definition:

Validity period (in seconds) of the obtained temporary security credential.

Constraints:

Validity period (in seconds) of the obtained temporary security credential. Note that the duration must be less than the maximum session duration set for the trust agency. The final session duration will be determined as the shortest among duration_seconds, the value of SessionNotOnOrAfter in the SAML authentication response, and the value of SessionDuration.

Range:

The value ranges from 900 to 43200.

Default Value:

The default value is 3600.

policy

No

String

Definition :

Custom policy. For details, see Reference.

Constraints:

The permission scope of the temporary security credential obtained in this session cannot exceed the permission scope specified in the custom policy.

The value contains 2 to 2,048 characters.

Range:

N/A.

Default Value:

N/A.

policy_ids

No

Array of strings

Definition:

List of preset policies. The permission scope of the temporary security credential obtained in this session cannot exceed the permission scope specified in the preset policies.

Constraints:

N/A.

Range:

N/A.

Default Value:

N/A.

provider_urn

Yes

String

Definition:

URN of the SAML provider.

Constraints:

The value contains 0 to 1,500 characters.

Range:

N/A.

Default Value:

N/A.

agency_urn

Yes

String

Definition:

URN of a target trust agency.

Constraints:

The value contains 0 to 1,500 characters.

Range:

N/A.

Default Value:

N/A.

saml_assertion

Yes

String

Definition:

Base64-encoded SAML authentication response provided by the SAML identity provider.

Constraints:

The value contains 4 to 100,000 characters.

Range:

N/A.

Default Value:

N/A.

Response Parameters

Status code: 200

Table 2 Response body parameters

Parameter

Type

Description

source_identity

String

Definition:

Identity declared by the value of the SourceIdentity attribute in the SAML assertion.

Constraints:

N/A.

assumed_agency

AssumedAgencyWithFederationDto object

Definition:

Trust agency session information.

Range:

N/A

credentials

CredentialsDto object

Definition:

Generated temporary security credentials.

Range:

N/A.

audience

String

Definition:

Recipient attribute value of the SubjectConfirmationData element in the SAML assertion.

Constraints:

N/A.

issuer

String

Definition:

Value of the Issuer element in the SAML assertion.

Constraints:

N/A.

name_qualifier

String

Definition:

Hash value of the following three parts: issuer, Huawei Cloud account ID, and SAML provider name (the last part of the URN) in IAM. The combination of name_qualifier and subject can be used to uniquely identify a user. The following pseudocode shows how to calculate the hash value: BASE64 (SHA1 ("https://example.com/saml" + "8c1eef3a241945f69c3d3axxxxxxxxxx" + "/MySAMLIdPName"))

Constraints:

N/A.

subject

String

Definition:

Value of the NameID element of the Subject element in the SAML assertion.

Constraints:

N/A.

subject_type

String

Definition:

Format of the NameID, defined by the Format attribute of the NameID element in the SAML assertion. A typical example of the format is transient or persistent. If the format contains the prefix urn:oasis:names:tc:SAML:2.0:nameid-format, the prefix will be removed. For example, urn:oasis:names:tc:SAML:2.0:nameid-format:transient will be returned as transient. If the format contains any other prefix, the format is returned without any modification.

Constraints:

N/A.
Table 3 AssumedAgencyWithFederationDto

Parameter

Type

Description

urn

String

Definition:

URN of the trust agency session.

Range:

N/A

id

String

Definition:

Unique identifier of a trust agency session, including the trust agency ID and trust agency session name.

Range:

N/A
Table 4 CredentialsDto

Parameter

Type

Description

access_key_id

String

Definition:

AK of the temporary security credential.

Range:

N/A

expiration

String

Definition:

Expiration time of the temporary security credential.

Range:

N/A

secret_access_key

String

Definition:

SK of the temporary security credential.

Range:

N/A

security_token

String

Definition:

security_token of the temporary security credential.

Range:

N/A

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_code

String

Definition :

Error code. For details, see Error Code.

Range:

The format is STS5.XXXX, for example, STS5.1001.

error_msg

String

Definition :

Error message. For details, see Error Message.

Range:

N/A.

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Definition :

Error code. For details, see Error Code.

Range:

The format is STS5.XXXX, for example, STS5.1001.

error_msg

String

Definition :

Error message. For details, see Error Message.

Range:

N/A.

encoded_authorization_message

String

Definition :

Encrypted details returned when the authentication fails, which are used to locate authentication problems. The STS5 decryption API can be used for decryption. For details, see API link.

Range:

N/A.

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Definition :

Error code. For details, see Error Code.

Range:

The format is STS5.XXXX, for example, STS5.1001.

error_msg

String

Definition :

Error message. For details, see Error Message.

Range:

N/A.

Status code: 500

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Definition :

Error code. For details, see Error Code.

Range:

The format is STS5.XXXX, for example, STS5.1001.

error_msg

String

Definition :

Error message. For details, see Error Message.

Range:

N/A.

Example Requests

Obtaining a temporary security credential using the SAML assertion and the trust agency Y0yfCQYJGO of account 27680d67da6b47eb82d00a1a118be145

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

Example Responses

Status code: 200

Request succeeded.

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

Status Codes

Status Code

Description

200

Request succeeded.

400

Abnormal request body.

403

No permissions.

404

No resources found.

500

Server error.

Error Codes

See Error Codes.