Use Alibaba Cloud CLI to call STS OpenAPI - Resource Access Management

Prerequisites

Before you proceed, familiarize yourself with the following concepts:

Step 1: Install Alibaba Cloud CLI

Install Alibaba Cloud CLI before use. Installation packages are available for Windows, Linux, and macOS. Select the appropriate package for your operating system.

Windows: Install Alibaba Cloud CLI on Windows.
Linux: Install or update Alibaba Cloud CLI.
macOS: Install Alibaba Cloud CLI on macOS.

You can also use Cloud Shell to debug Alibaba Cloud CLI commands. For more information, see What is Cloud Shell?.

Step 2: Configure Alibaba Cloud CLI

Important

You can call the AssumeRole API operation only as a RAM user or by assuming a RAM role. You cannot call the operation with an Alibaba Cloud account (root account). The example in this topic uses a RAM user.

Before you use Alibaba Cloud CLI, configure your credentials and a region ID. Alibaba Cloud CLI supports multiple credential types. For more information, see Configure and manage credentials. This example uses an AccessKey pair. Follow these steps:

Create a RAM user and an AccessKey pair to use for configuration. For more information, see Create a RAM user and Create an AccessKey.
Grant permissions to the RAM user. In this example, you must grant the RAM user permission to call the AssumeRole API operation of STS by attaching the AliyunSTSAssumeRoleAccess policy. For more information, see Manage RAM user permissions.
Obtain the ID of an available region. Alibaba Cloud CLI sends API requests to the region that you specify. For a list of available STS regions, see Endpoints.

Note
When you use Alibaba Cloud CLI, you can add the --region option to a command to specify a region for the request. If you add this option, it overrides the region specified in your profile and environment variables. For more information, see Command-line options.
Use the AccessKey pair of the RAM user to configure the credentials. Name the configuration profile AkProfile. For more information, see Configure and manage credentials.

Step 3: Create a RAM role

Important

The Alibaba Cloud Resource Name (ARN) of the role, specified by the RoleArn parameter, is required to call the AssumeRole API operation. To obtain the ARN, create a RAM role that trusts an Alibaba Cloud account.

In this example, you use the RAM user that you created in Step 2: Configure Alibaba Cloud CLI to assume this role. Therefore, the trusted Alibaba Cloud account must be set to the ID of the Alibaba Cloud account to which the RAM user from Step 2: Configure Alibaba Cloud CLI belongs. For more information, see Create a RAM role for a trusted Alibaba Cloud account.

You can modify the RAM role's trust policy to specify which RAM users can assume the role. For more information, see Modify the trust policy of a RAM role.

Step 4: Generate a CLI command example

In OpenAPI Explorer, go to the AssumeRole debugging page.
On the Parameters tab, enter the request parameters. Then, click the CLI Example tab to view the generated command.
Run the command in Cloud Shell or copy the command example.
- Click Run in Cloud Shell to open Cloud Shell and quickly debug the command.
- Click Repeat to copy the command to your clipboard. You can then paste it into your local shell to run it.
  Note
  - If you copy the command to a local shell for debugging, make sure that the parameter format is correct. For more information about Alibaba Cloud CLI command parameters, see Understand command parameters.
  - By default, OpenAPI Explorer adds the --region option to the generated command. When you run the command locally, this option overrides the region settings in your default profile and environment variables. You can keep or remove this option as needed.

Step 5: Call STS APIs

Example 1: List available STS APIs

The following example uses the --help option to list the STS API operations available in Alibaba Cloud CLI. You can also view available API operations in API overview.

Run the command.
```
aliyun sts --help
```

The following output is returned.

Usage:
  aliyun sts <ApiName> --parameter1 value1 --parameter2 value2 ...
Product: Sts (Security Token Service)
Version: 2015-04-01
Available Api List:
  AssumeRole            Calls the AssumeRole operation to obtain temporary security credentials (an STS Token) to assume a RAM role.
  AssumeRoleWithOIDC    [Anonymous] Calls the AssumeRoleWithOIDC operation to obtain temporary security credentials (an STS Token) for a RAM role during OIDC-based role SSO.
  AssumeRoleWithSAML    [Anonymous] Calls the AssumeRoleWithSAML operation to obtain temporary security credentials (an STS Token) for a RAM role during SAML-based role SSO.
  GetCallerIdentity     Calls the GetCallerIdentity operation to obtain information about the current caller's identity.

Example 2: Assume a RAM role

The following example calls the AssumeRole command to obtain temporary security credentials for assuming a RAM role.

Run the command.

Note

To get help with command parameters:

Run the aliyun sts AssumeRole --help command to get parameter suggestions.
See the AssumeRole topic for detailed parameter descriptions.

aliyun sts AssumeRole \
  --DurationSeconds 3600 \
  --Policy '{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}' \
  --RoleSessionName alice \
  --RoleArn 'acs:ram::123456789012****:role/adminrole' \
  --ExternalId abcd1234

The following output is an example. The SecurityToken value is the temporary security credential.

{
  "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F",
  "AssumedRoleUser": {
    "AssumedRoleId": "34458433936495****:alice",
    "Arn": "acs:ram::123456789012****:role/adminrole/alice"
  },
  "Credentials": {
    "SecurityToken": "********",
    "Expiration": "2015-04-09T11:52:19Z",
    "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
    "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****"
  }
}

Note

If an error occurs when you call an STS API operation, check the returned error code to verify that your request parameters and values are valid.

You can use the request ID from the response or SDK error message with OpenAPI Troubleshoot to diagnose the issue.