Configure StsToken credentials for Alibaba Cloud CLI - Alibaba Cloud CLI

Configure STS temporary credentials for Alibaba Cloud CLI using the StsToken method. The CLI uses the provided credentials directly without automatic refresh. You must obtain and reconfigure new credentials after expiration.

Prerequisites

Alibaba Cloud CLI 3.3.0 or later is installed. Run aliyun version to check. If earlier than 3.3.0, upgrade per Install/Update CLI.
A valid STS temporary credential obtained via the AssumeRole API or other methods. The credential includes:
- An AccessKey ID (typically starts with STS.)
- An AccessKey Secret
- A security token
The credential expiration time is known. STS credentials typically expire within 15 minutes to 1 hour, depending on the DurationSeconds value set when the token was issued.

Configure credentials

Configure StsToken credentials interactively or non-interactively.

Interactive configuration

Run the following command. Replace <ProfileName> with a custom 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.

The terminal displays Configure Done and a welcome message when the configuration succeeds.

Non-interactive configuration

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

Complete parameters

Parameter	Description	Required	Example
`--mode`	Credential type. Must be `StsToken`.	Yes	`StsToken`
`--profile`	Profile name. Defaults to the active profile if omitted. The initial profile is named `default`. Use a descriptive name to distinguish credential sets.	No	`StsProfile`
`--access-key-id`	Temporary AccessKey ID. Typically starts with `STS.`.	Yes	`STS.NUr5xxxxx`
`--access-key-secret`	Temporary AccessKey Secret.	Yes	`7Bshxxxxx`
`--sts-token`	Security token string.	Yes	`CAISxxxxxxxx...`
`--region`	Default region ID, such as `cn-hangzhou`.	Yes	`cn-hangzhou`

Note

The configured profile automatically becomes active. To switch profiles, run aliyun configure switch --profile <ProfileName>.

Verify the configuration

Run the following command to verify the credential:

aliyun sts get-caller-identity

Sample output. The Arn field shows the RAM role and session name associated with the 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 expiration

STS credentials are not automatically refreshed. Expired credentials produce 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", ...}

Obtain a new credential and run the configuration command again. For automatic renewal, use the RamRoleArn or EcsRamRole credential type instead.

Delete a credential

Run the following command to delete an StsToken profile:

aliyun configure delete --profile <ProfileName>

FAQs

Do I need to delete the old profile before updating an expired STS token?

No. Run aliyun configure set with the same profile name to overwrite the existing credentials without a confirmation prompt.

Can I configure StsToken using environment variables?

Yes. The CLI prioritizes the configuration profile but falls back to environment variables for any missing values:

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