Configure RamRoleArn or ChainableRamRoleArn in Alibaba Cloud CLI to automatically obtain STS temporary credentials through RAM role assumption, avoiding exposure of long-term AccessKeys. - Alibaba Cloud CLI

By configuring Alibaba Cloud CLI to assume a RAM role, you can use a low-privilege AccessKey to automatically obtain temporary STS credentials for accessing cloud resources, without directly exposing a high-privilege AccessKey. This topic describes two configuration methods—RamRoleArn (directly assuming a RAM role) and ChainableRamRoleArn (assuming a RAM role by chaining from existing CLI credentials)—and their applicable scenarios.

Version requirement

Alibaba Cloud CLI version ≥ 3.3.0. Run aliyun version to check the current version. If the version is earlier, see Install, update, and uninstall Alibaba Cloud CLI to upgrade.

RamRoleArn

RamRoleArn uses a low-privilege AccessKey to assume a higher-privilege RAM role and obtain temporary STS credentials. The AccessKey only needs the AliyunSTSAssumeRoleAccess policy. The effective permissions are determined by the policies attached to the target role. This method is suitable for local development environments and scenarios that require privilege separation.

Prerequisites

An AccessKey has been created for the RAM user and the AliyunSTSAssumeRoleAccess policy has been granted.
A target RAM role has been created, and the trust policy of the role allows the RAM user to assume the role.
The ARN of the target RAM role has been obtained. You can view it on the role details page in the RAM console. The format is acs:ram::<ACCOUNT_ID>:role/<RoleName>.

For detailed prerequisite preparation, see the steps under Indirectly use an AccessKey in Use an AccessKey pair for API calls.

Configure credentials

Interactive configuration

Run the following command to start the configuration. Replace <ProfileName> with a custom profile name (for example, RamRoleProfile):
```
aliyun configure --mode RamRoleArn --profile <ProfileName>
```

Enter the configuration information as prompted:

Configuring profile 'RamRoleArnProfile' in 'RamRoleArn' authenticate mode...
Access Key Id []: <yourAccessKeyID>
Access Key Secret []: <yourAccessKeySecret>
Sts Region []: cn-hangzhou
Ram Role Arn []: acs:ram::012345678910****:role/Alice
Role Session Name []: alice
External ID []: abcd1234
Expired Seconds [900]: 900
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[RamRoleArnProfile] ...Done.

When the terminal displays Configure Done followed by a welcome message, the configuration is complete.

Note

After the configuration succeeds, the profile automatically becomes the active profile. To switch to another profile, run the aliyun configure switch --profile <ProfileName> command.

Non-interactive configuration

Bash

aliyun configure set \
  --profile RamRoleArnProfile \
  --mode RamRoleArn \
  --access-key-id <yourAccessKeyID> \
  --access-key-secret <yourAccessKeySecret> \
  --sts-region "cn-hangzhou" \
  --ram-role-arn "acs:ram::012345678910****:role/Alice" \
  --role-session-name "alice" \
  --external-id "abcd1234" \
  --expired-seconds 900 \
  --region "cn-shanghai"

PowerShell

aliyun configure set `
  --profile RamRoleArnProfile `
  --mode RamRoleArn `
  --access-key-id <yourAccessKeyID> `
  --access-key-secret <yourAccessKeySecret> `
  --sts-region "cn-hangzhou" `
  --ram-role-arn "acs:ram::012345678910****:role/Alice" `
  --role-session-name "alice" `
  --external-id "abcd1234" `
  --expired-seconds 900 `
  --region "cn-shanghai"

Full parameters

Parameter	Required	Description	Example
`--mode`	Yes	Fixed value `RamRoleArn`. Specifies the credential type.	`RamRoleArn`
`--profile`	No	Profile name. If not specified, the currently active profile is used by default. The default name for the first profile is `default`. We recommend that you use a meaningful name to distinguish between multiple profiles.	`RamRoleProfile`
`--region`	Yes	Default region ID.	`cn-hangzhou`
`--access-key-id`	Yes	AccessKey ID of the RAM user. The user must have the `AliyunSTSAssumeRoleAccess` policy.	`LTAI5t****`
`--access-key-secret`	Yes	The corresponding AccessKey Secret.	`****`
`--ram-role-arn`	Yes	ARN of the target RAM role. You can obtain it from the role details page on the RAM console.	`acs:ram::191317683912****:role/DevOpsRole`
`--role-session-name`	Yes	Session name, used to identify this role assumption in audit logs. We recommend that you use a meaningful identifier such as an application name or machine name.	`my-session`
`--expired-seconds`	No	Validity period of the temporary credentials in seconds. Valid values: 900 to 3600. The default value is 900 seconds in interactive configuration. If not specified in the `configure set` command, the default value is 3600 seconds.	`900`
`--external-id`	No	External ID, used to enhance security during cross-account role assumption. This parameter is required only when the trust policy of the target role requires it. For more information, see Prevent the confused deputy problem with external IDs.
`--sts-region`	No	Region ID of the STS endpoint. If not specified, the global endpoint `sts.aliyuncs.com` is used.	`cn-shanghai`

Verify credentials

After the configuration is complete, run the following command to verify that the credentials are effective:

aliyun sts get-caller-identity

Output:

{
  "AccountId": "191317683912****",
  "Arn": "acs:ram::191317683912****:assumed-role/<role-name>/<role-session-name>",
  "IdentityType": "AssumedRoleUser",
  "PrincipalId": "30004467717606****:<role-session-name>",
  "RequestId": "0FFADC33-EA49-5E2A-977F-0BA820D6****",
  "RoleId": "30004467717606****"
}

Credential refresh

The CLI automatically manages credential refresh without manual intervention. Before the STS temporary credentials expire, the CLI automatically calls STS AssumeRole again to obtain new credentials. This does not affect CLI commands that are being executed.

ChainableRamRoleArn

ChainableRamRoleArn assumes another RAM role by chaining from an existing CLI credential profile (the source profile). The CLI first obtains intermediate credentials from the source profile, and then uses those credentials to call STS AssumeRole and obtain the final temporary STS credentials. This method is suitable for cross-account, multi-hop role chaining scenarios, or for scenarios where you need to assume additional roles based on an EcsRamRole.

The ChainableRamRoleArn credential type works by specifying a source credential profile, obtaining intermediate credentials (an AccessKey or temporary STS credentials) from that profile, and then using those intermediate credentials to assume the target role and obtain the final temporary STS credentials.

Prerequisites

A valid CLI profile (source profile) already exists, such as a configured EcsRamRole, AK, or RamRoleArn profile.
The principal (RAM user or role) associated with the source profile has permission to assume the target RAM role (the trust policy of the target role allows the principal to assume it).
The ARN of the target RAM role has been obtained, in the format acs:ram::<ACCOUNT_ID>:role/<RoleName>.

Configure credentials

Interactive configuration

Run the following command to start the configuration. Replace <ProfileName> with a custom profile name (for example, ChainProfile):
```
aliyun configure --mode ChainableRamRoleArn --profile <ProfileName>
```

Enter the configuration information as prompted:

Configuring profile 'ChainableProfile' in 'ChainableRamRoleArn' authenticate mode...
Source Profile []: RamRoleArnProfile
Sts Region []: cn-hangzhou
Ram Role Arn []: acs:ram::012345678910****:role/Alice
Role Session Name []: alice
External ID []: abcd1234
Expired Seconds [900]: 900
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[ChainableProfile] ...Done.

Note

In the preceding example, RamRoleArnProfile is the name of an existing source profile, and the RAM role ARN is an example value. Replace them with actual values. You can press Enter to skip the Sts Region and External Id prompts.

When the terminal displays Configure Done followed by a welcome message, the configuration is complete.

Note

After the configuration succeeds, the profile automatically becomes the active profile. To switch to another profile, run the aliyun configure switch --profile <ProfileName> command.

Non-interactive configuration

Command example:

Bash

aliyun configure set \
  --profile ChainableProfile \
  --mode ChainableRamRoleArn \
  --source-profile RamRoleArnProfile \
  --sts-region "cn-hangzhou" \
  --ram-role-arn "acs:ram::012345678910****:role/Alice" \
  --role-session-name "alice" \
  --external-id "abcd1234" \
  --expired-seconds 900 \
  --region "cn-shanghai"

PowerShell

aliyun configure set `
  --profile ChainProfile `
  --mode ChainableRamRoleArn `
  --region cn-hangzhou `
  --source-profile EcsRoleProfile `
  --ram-role-arn acs:ram::<UID>:role/<RoleName> `
  --role-session-name chain-session `
  --expired-seconds 900

Important

The profile specified by --source-profile must already exist in the CLI configuration file. Otherwise, the error can not load the source profile: <name> is returned. Run aliyun configure list to view all existing profiles.

Full parameters

Parameter	Required	Description	Example
`--mode`	Yes	Fixed value `ChainableRamRoleArn`. Specifies the credential type. Must be specified explicitly and does not support automatic inference.	`ChainableRamRoleArn`
`--profile`	No	Profile name. If not specified, the currently active profile is used by default. The default name for the first profile is `default`.	`ChainProfile`
`--region`	Yes	Default region ID.	`cn-hangzhou`
`--source-profile`	Yes	Name of the source profile. The CLI first obtains intermediate credentials from this profile and then uses the intermediate credentials to assume the target role. The profile must already exist.	`EcsRoleProfile`
`--ram-role-arn`	Yes	ARN of the target RAM role.	`acs:ram::191317683912****:role/CrossAccountRole`
`--role-session-name`	Yes	Session name, used for identification in audit logs.	`chain-session`
`--expired-seconds`	No	Validity period of the temporary credentials in seconds. Valid values: 900 to 3600. If not specified, the default value is 3600 seconds.	`900`
`--external-id`	No	External ID. This parameter is required only when the trust policy of the target role requires it.
`--sts-region`	No	Region ID of the STS endpoint. If not specified, the global endpoint `sts.aliyuncs.com` is used.	`cn-hangzhou`

Verify credentials

After the configuration is complete, run the aliyun sts get-caller-identity command to verify that the credentials are effective.

Credential refresh

The CLI automatically manages credential refresh without manual intervention. Before the STS temporary credentials expire, the CLI first refreshes the credentials of the source profile (following the refresh logic of the source profile, for example, EcsRamRole refreshes through IMDS), and then calls STS AssumeRole again to obtain new credentials.

Delete credentials

Delete the RAM role credentials from the CLI local configuration:

aliyun configure delete --profile <ProfileName>

Note

If the deleted profile is the currently active profile, the CLI automatically switches to the first profile in the profile list.