Skip to main content

STS token

StsToken carries temporary credentials issued elsewhere: an AccessKey ID, an AccessKey secret, and a security token. ecctl uses them exactly as given and cannot refresh them. When they expire, the command fails and something outside ecctl must issue a new set.

Use this mode when another system already vends short-lived credentials, such as a CI job that calls STS AssumeRole itself. When ecctl should do the assuming, use RAM role ARN instead. When the credentials should be fetched and renewed from an endpoint, use Credentials URI.

Configure with ecctl​

ecctl configure set access-key-id <temporary-id>
ecctl configure set access-key-secret <temporary-secret>
ecctl configure set security-token <token>

security-token is stored as sts_token. Setting it on a profile that already holds an AccessKey pair switches that profile from AK to StsToken.

ecctl configure --mode StsToken is not supported. --mode accepts OAuth only.

Configure with Alibaba Cloud CLI​

aliyun configure --mode StsToken --profile ci

Configure with environment variables​

export ALIBABA_CLOUD_ACCESS_KEY_ID=<temporary-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<temporary-secret>
export ALIBABA_CLOUD_SECURITY_TOKEN=<token>

All three are required. An AccessKey pair without a security token resolves as AK, not as a partial StsToken. Each variable also accepts an ALIBABACLOUD_, ALICLOUD_, or bare spelling.

Profile fields​

FieldRequiredNotes
modeNoStsToken. Inferred when sts_token is present alongside an AccessKey pair
access_key_idYesTemporary AccessKey ID, usually prefixed STS.
access_key_secretYesTemporary AccessKey secret
sts_tokenYesThe security token
sts_expirationNoUnix timestamp in seconds. Enables expiry checking
{
  "name": "ci",
  "mode": "StsToken",
  "access_key_id": "STS.NUgYrLnoC...",
  "access_key_secret": "...",
  "sts_token": "...",
  "sts_expiration": 1782460800,
  "region_id": "cn-hangzhou"
}

sts_expiration is a Unix timestamp in seconds, not an RFC 3339 string.

Expiration behavior​

Without sts_expiration, ecctl sends the credential and lets the service decide. An expired token then fails at the API with a service-side error.

With sts_expiration, ecctl rejects an expired token before signing, and rejects a token that cannot cover a known command deadline. This turns a mid-transfer failure into an immediate local error, which is much easier to diagnose during a long operation.

Because StsToken cannot refresh itself, a long OSS transfer needs a sts_expiration comfortably beyond the transfer window. When you cannot guarantee that, switch to a renewable mode: OAuth, OIDC, RAM role ARN, ECS RAM role, External, or Credentials URI.

Verify​

ecctl --profile ci configure get
ecctl --profile ci --region cn-hangzhou ecs region list

A malformed security token is rejected by the service, so it surfaces as a service error with code CloudAPIError naming the response, for example Specified SecurityToken is malformed. That response carries a request ID, which means resolution and signing succeeded locally and the service rejected the token itself. A client-side InvalidCredentials or MissingCredentials error, with no request ID, means the credential never resolved.