Configure CLI with an StsToken - Alibaba Cloud CLI - Alibaba Cloud Documentation Center

If you have an STS temporary credential, you can configure it for the Alibaba Cloud CLI by using the StsToken mode. In this mode, the CLI uses the provided credential directly and does not automatically refresh it. When the credential expires, you must obtain a new one and overwrite the configuration.

Prerequisites

Alibaba Cloud CLI version 3.3.0 or later. Run aliyun version to check your current version. If your version is earlier than 3.3.0, see Install/Update CLI to upgrade.
You have obtained a valid STS temporary credential by calling the AssumeRole API or through other methods. The credential includes the following:
- An AccessKey ID, which typically starts with STS.
- An AccessKey Secret
- A security token
Note the credential's expiration time. A temporary security credential typically expires within 15 minutes to 1 hour, depending on the validity period (DurationSeconds) set when the STS token was obtained.

Configure credentials

You can configure the temporary credential for the Alibaba Cloud CLI using either interactive or non-interactive methods.

Interactive configuration

Run the following command to start the configuration. Replace <ProfileName> with a custom profile name, such as StsProfile.
```
aliyun configure --mode StsToken --profile <ProfileName>
```

Enter your credential information at the prompts:

Configuring profile 'StsProfile' in 'StsToken' authenticate mode...
Access Key Id []: STS.NUr5xxxxx
Access Key Secret []: 7Bshxxxxx
Sts Token []: CAISxxxxxxxxxxxxxxxx...
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[StsProfile] ...Done.

When the terminal displays Saving profile[...] ...Done. and a welcome message, the configuration is complete.

Non-interactive configuration

Command examples:

Bash

aliyun configure set \
  --profile StsProfile \
  --mode StsToken \
  --access-key-id STS.NUr5xxxxx \
  --access-key-secret 7Bshxxxxx \
  --sts-token CAISxxxxxxxxxxxxxxxx... \
  --region cn-shanghai

PowerShell

aliyun configure set `
  --profile StsProfile `
  --mode StsToken `
  --access-key-id STS.NUr5xxxxx `
  --access-key-secret 7Bshxxxxx `
  --sts-token CAISxxxxxxxxxxxxxxxx... `
  --region cn-shanghai

Parameters

Parameter	Description	Required	Example
`--mode`	Specifies the credential type. The value must be `StsToken`.	Yes	`StsToken`
`--profile`	The profile name. If you do not specify this parameter, the CLI uses the active profile. The default profile name for the first configuration is `default`. We recommend using a descriptive name to distinguish between multiple credential sets.	No	`StsProfile`
`--access-key-id`	The temporary AccessKey ID. It typically starts with `STS.`.	Yes	`STS.NUr5xxxxx`
`--access-key-secret`	The temporary AccessKey Secret.	Yes	`7Bshxxxxx`
`--sts-token`	The security token string.	Yes	`CAISxxxxxxxx...`
`--region`	The default region ID, for example, `cn-hangzhou`.	Yes	`cn-hangzhou`

Note

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

Verify the configuration

After completing the configuration, run the following command to verify the credential:

aliyun sts get-caller-identity

The output is similar to the following. The Arn field shows the RAM role name and role session name associated with the current STS token.

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

Credential refresh

STS temporary credentials are not automatically refreshed. After a credential expires, running any CLI command returns the following error:

Error: request execution failed: request execution failed: SDKError:
   StatusCode: 400
   Code: InvalidSecurityToken.Expired
   Message: code: 400, Specified SecurityToken is expired. request id: 9C518A52-BE37-570A-8E1A-0DD559BC****
   Data: {"Code":"InvalidSecurityToken.Expired", ...}

After obtaining a new temporary credential, run the configuration command again. To enable automatic credential renewal, we recommend using the RamRoleArn or EcsRamRole credential type instead.

Delete a credential

To delete an StsToken credential from your local CLI configuration, run the following command:

aliyun configure delete --profile <ProfileName>

FAQ

Updating an expired STS token

No. You can run the aliyun configure set command with the same profile name to overwrite the existing profile. This action replaces the old credential values without a confirmation prompt.

Using environment variables

The CLI prioritizes credentials from the configuration profile. If a profile is configured but is missing values, the CLI automatically uses the corresponding environment variables to provide the missing values.

export ALIBABA_CLOUD_ACCESS_KEY_ID="STS.xxx"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="tempSecret"
export ALIBABA_CLOUD_SECURITY_TOKEN="token-string"