All Products
Search
Document Center

Resource Access Management:AssumeRoleWithOIDC

Last Updated:Jul 25, 2024

Queries a Security Token Service (STS) token to assume a Resource Access Management (RAM) role during role-based single sign-on (SSO) by using OpenID Connect (OIDC).

Operation description

Prerequisites

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
OIDCProviderArnstringYes

The Alibaba Cloud Resource Name (ARN) of the OIDC IdP.

You can view the ARN in the RAM console or by calling operations.

acs:ram::113511544585****:oidc-provider/TestOidcIdp
RoleArnstringYes

The ARN of the RAM role.

You can view the ARN in the RAM console or by calling operations.

acs:ram::113511544585****:role/testoidc
OIDCTokenstringYes

The OIDC token that is issued by the external IdP.

The OIDC token must be 4 to 20,000 characters in length.

Note You must enter the original OIDC token. You do not need to enter the Base64-encoded OIDC token.
eyJraWQiOiJKQzl3eHpyaHFKMGd0****
PolicystringNo

The policy that specifies the permissions of the returned STS token. You can use this parameter to grant the STS token fewer permissions than the permissions granted to the RAM role.

  • If you specify this parameter, the permissions of the returned STS token are the permissions that are included in the value of this parameter and owned by the RAM role.
  • If you do not specify this parameter, the returned STS token has all the permissions of the RAM role.

The value must be 1 to 2,048 characters in length.

{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
DurationSecondslongNo

The validity period of the STS token. Unit: seconds.

Default value: 3600. Minimum value: 900. Maximum value: the value of the MaxSessionDuration parameter.

For more information about how to specify MaxSessionDuration, see CreateRole or UpdateRole .

3600
RoleSessionNamestringYes

The custom name of the role session.

Set this parameter based on your business requirements. In most cases, this parameter is set to the identity of the user who calls the operation, for example, the username. In ActionTrail logs, you can distinguish the users who assume the same RAM role to perform operations based on the value of the RoleSessionName parameter. This way, you can perform user-specific auditing.

The value can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_).

The value must be 2 to 64 characters in length.

TestOidcAssumedRoleSession
Note Anonymous users can call the AssumeRoleWithOIDC operation because authentication for this operation is performed based on OIDC tokens. Therefore, you do not need to specify the following common request parameters: Signature, SignatureMethod, SignatureVersion, and AccessKeyId. For more information about common request parameters, see Common request parameters.

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The ID of the request.

3D57EAD2-8723-1F26-B69C-F8707D8B565D
OIDCTokenInfoobject

The information about the OIDC token.

Subjectstring

The subject,

which is represented by the sub field in the OIDC Token.

KryrkIdjylZb7agUgCEf****
Issuerstring

The URL of the issuer,

which is represented by the iss field in the OIDC Token.

https://dev-xxxxxx.okta.com
ClientIdsstring

The audience. If multiple audiences are returned, the audiences are separated by commas (,).

The audience is represented by the aud field in the OIDC Token.

496271242565057****
ExpirationTimestring

The time when the OIDC token expires.

2021-10-20T04:27:09Z
IssuanceTimestring

The time when the OIDC token was issued.

2021-10-20T03:27:09Z
VerificationInfostring

The verification information about the OIDC token. For more information, see Manage an OIDC IdP.

Success
AssumedRoleUserobject

The temporary identity that you use to assume the RAM role.

AssumedRoleIdstring

The ID of the temporary identity that you use to assume the RAM role.

33157794895460****
Arnstring

The ARN of the temporary identity that you use to assume the RAM role.

acs:ram::113511544585****:role/testoidc/TestOidcAssumedRoleSession
Credentialsobject

The access credentials.

SecurityTokenstring

The STS token.

Note Alibaba Cloud STS does not impose limits on the length of STS tokens. We strongly recommend that you do not specify a maximum length for STS tokens.
CAIShwJ1q6Ft5B2yfSjIr5bSEsj4g7BihPWGWHz****
Expirationstring

The time when the STS token expires. The time is displayed in UTC.

2021-10-20T04:27:09Z
AccessKeySecretstring

The AccessKey secret.

CVwjCkNzTMupZ8NbTCxCBRq3K16jtcWFTJAyBEv2****
AccessKeyIdstring

The AccessKey ID.

STS.NUgYrLnoC37mZZCNnAbez****

Examples

Sample success responses

JSONformat

{
  "RequestId": "3D57EAD2-8723-1F26-B69C-F8707D8B565D",
  "OIDCTokenInfo": {
    "Subject": "KryrkIdjylZb7agUgCEf****",
    "Issuer": "https://dev-xxxxxx.okta.com",
    "ClientIds": "496271242565057****",
    "ExpirationTime": "2021-10-20T04:27:09Z",
    "IssuanceTime": "2021-10-20T03:27:09Z",
    "VerificationInfo": "Success"
  },
  "AssumedRoleUser": {
    "AssumedRoleId": "33157794895460****",
    "Arn": "acs:ram::113511544585****:role/testoidc/TestOidcAssumedRoleSession"
  },
  "Credentials": {
    "SecurityToken": "CAIShwJ1q6Ft5B2yfSjIr5bSEsj4g7BihPWGWHz****",
    "Expiration": "2021-10-20T04:27:09Z",
    "AccessKeySecret": "CVwjCkNzTMupZ8NbTCxCBRq3K16jtcWFTJAyBEv2****",
    "AccessKeyId": "STS.NUgYrLnoC37mZZCNnAbez****"
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-04-11The internal configuration of the API is changed, but the call is not affectedView Change Details
2023-09-27The response structure of the API has changedView Change Details