Use Alibaba Cloud CLI to call the API operations of STS - Resource Access Management

Alibaba Cloud CLI is a general-purpose command-line tool that is developed based on APIs. You can use Alibaba Cloud CLI to implement automatic management and maintenance of Security Token Service (STS). This topic describes how to use Alibaba Cloud CLI to call the API operations of STS. In this example, the AssumeRole operation of STS is called to obtain temporary identity credentials.

Before you start

Before you read this topic, you may need to understand the following concepts:

Step 1: Install Alibaba Cloud CLI

You must install Alibaba Cloud CLI before you can use it. Alibaba Cloud CLI supports Windows, Linux, and macOS. When you install Alibaba Cloud CLI, select the installation package based on the operating system of your device.

You can also use Alibaba Cloud Cloud Shell to debug the commands that you want to run in Alibaba Cloud CLI. For more information about Cloud Shell, see What is Cloud Shell?

Step 2: Configure Alibaba Cloud CLI

Important

You can call the AssumeRole operation only as a Resource Access Management (RAM) user or a RAM role. You cannot use an Alibaba Cloud account to call the operation. In this example, a RAM user is used to call the operation.

Before you use Alibaba Cloud CLI, you must specify your identity credentials and region ID in Alibaba Cloud CLI. Alibaba Cloud CLI supports various types of identity credentials. For more information, see the "Credential types" section of the Configure profiles topic. In this example, AccessKey pairs are used as identity credentials.

Create a RAM user and create an AccessKey pair for the RAM user. For more information, see Create a RAM user and Create an AccessKey pair.
Grant the required permissions to the RAM user. In this example, the AliyunSTSAssumeRoleAccess policy is attached to the RAM user. The policy grants the permissions to call the AssumeRole operation of STS. For more information, see Grant permissions to a RAM user.
Obtain the ID of the region that you want to use. Alibaba Cloud CLI uses the region ID that you specify to initiate API calls. For more information, see Endpoints.
Note
When you use Alibaba Cloud CLI, you can use the --region option to run a command in a specific region. If you use the option, Alibaba Cloud CLI ignores the region information in the default credential settings and environment variables. For more information, see Command line options for API calls.
Use the AccessKey pair of the RAM user to configure identity credentials in the AkProfile configuration file. For more information, see the "Configuration examples" section of the Configure profiles topic.

Step 3: Create a RAM role

Important

The RoleArn parameter indicates the Alibaba Cloud Resource Name (ARN) of a RAM role and is required to call the AssumeRole operation. To obtain the value of the parameter, you must create a RAM role for a trusted Alibaba Cloud.

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

You can also modify the trust policy that is attached to the RAM role to change the RAM user that can assume the RAM role. For more information, see Edit the trust policy of a RAM role.

Step 4: Generate a CLI command

In OpenAPI Explorer, call the AssumeRole operation.
On the Parameters tab, configure the request parameters. Then, click the CLI Example tab to view the generated sample command.
Run the CLI command in Cloud Shell or copy the CLI command.
- Click the icon to start Cloud Shell and debug the CLI command in Cloud Shell.
- Click the icon to copy the CLI command to the clipboard. You can also paste the CLI command into your on-premises shell to run the command.
  Note
  - When you paste the CLI command into your on-premises shell for debugging, take note of the parameter formats. For more information about the parameter formats required by Alibaba Cloud CLI, see Parameter formats.
  - By default, OpenAPI Explorer adds the --region option to the generated CLI command. When you copy the command to your local shell, Alibaba Cloud CLI ignores the region information in the default identity credential settings and environment variables, and preferentially runs the command in the region specified by the option. You can delete or retain the option based on your business requirements.

Step 5: Call the API operations of STS

Example 1: Query the STS API operations that can be called by using Alibaba Cloud CLI

The following code provides an example on how to use the --help option to query the STS API operations that can be called by using Alibaba Cloud CLI. You can also view the supported API operations in List of operations by function.

Run the following command:
```
aliyun sts --help
```
View the command output.

Example 2: Obtain the temporary identity credential of the RAM role that you want to assume

The following code provides an example on how to use Alibaba Cloud CLI to call the AssumeRole operation of STS. The operation is called to obtain the temporary identity credential of the RAM role that you want to assume.

Run the following commands:
Note
You can use one of the following methods to obtain the help information about command parameters:
- Run the aliyun sts AssumeRole --help command to obtain suggestions on command parameter.
- Read the AssumeRole topic to view parameter details.
```
aliyun sts AssumeRole \
  --DurationSeconds 3600 \
  --Policy '{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}' \
  --RoleSessionName alice \
  --RoleArn 'acs:ram::123456789012****:role/adminrole' \
  --ExternalId abcd1234
```
View the expected command output. The SecurityToken parameter in the output indicates the temporary identity credential that you query.
```
{
  "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 message is returned after you call an API operation of STS, you need to check whether the request parameters and the values of the request parameters are valid based on the returned error code.
You can also perform diagnostics based on the returned request ID or SDK error information on the OpenAPI problem diagnosis page.