Obtaining a Temporary Security Credential Through the OIDC SSO Trust Agency

Function

A set of temporary security credentials returned for users who have passed OIDC identity provider token authentication. This operation provides a mechanism that allows any external compatible OIDC 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 AssumeAgencyWithOIDC are valid for one hour. You can use the optional duration_seconds parameter to specify the session duration. 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 AssumeAgencyWithOIDC. The identity of the caller is verified using the public key in your JWKS endpoint.

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 your ID token. 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.

Identity:

Before your application can call AssumeAgencyWithOIDC, you must create an OIDC provider and a trust agency in IAM using your account, specify the OIDC provider in the trust policy of the trust agency, and configure your OIDC identity provider to issue the ID token 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:assumeWithOIDC	Write	agency *	g:ResourceTag/<tag-key>	-	sts::tagSession sts::setSourceIdentity
sts:agencies:assumeWithOIDC	Write	-	oidc:amr oidc:aud oidc:sub oidc:iss g:TagKeys g:RequestTag/<tag-key> sts:TransitiveTagKeys sts:SourceIdentity sts:AgencySessionName	-	sts::tagSession sts::setSourceIdentity

URI

POST /v5/agencies/assume-with-oidc

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: Note that the duration must be less than the maximum session duration set for the agency and cannot exceed 3,600 seconds when the X-Security-Token header is carried. 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 OIDC 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.
agency_session_name	Yes	String	Definition: Name of a trust agency session. Constraints: The value contains 2 to 128 characters. Range: N/A. Default Value: N/A.
id_token	Yes	String	Definition: OIDC token provided by an identity provider. Constraints: The value contains 4 to 20,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 in the OIDC token returned by an identity provider. Range: 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: Expected audience of the OIDC token (also called client ID), which is usually the client identifier distributed to an application. Range: N/A.
provider	String	Definition: Identity provider URN. Range: N/A.
subject_from_id_token	String	Definition: Unique user identifier returned by an identity provider, that is, the value of sub (subject) in the OIDC token. Range: 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 trust agency Y0yfCQYJGO of account 27680d67da6b47eb82d00a1a118be145 and the ID token

POST https://{endpoint}/v5/agencies/assume-with-oidc

{
  "duration_seconds" : 3600,
  "policy" : "{\"Version\":\"5.0\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"obs:bucket:listBucket\",\"Resource\":\"obs:*:*:bucket:productionapp\"}]}",
  "agency_urn" : "iam::27680d67da6b47eb82d00a1a118be145:agency:Y0yfCQYJGO",
  "agency_session_name" : "session1",
  "provider_urn" : "iam::27680d67da6b47eb82d00a1a118be145:oidcProvider:test",
  "id_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMzQ1In0...YeJ2hFNCyRwH4DKcfBKJ782m7xmIvQ"
}

Example Responses

Status code: 200

Request succeeded.

{
  "source_identity" : "DevUser123",
  "subject_from_id_token" : "sub-sample",
  "audience" : "client-id-test",
  "provider" : "iam::{account_id}:oidcProvider:test",
  "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"
  }
}