Configure CLI credentials - OAuth, AccessKey, RAM role, STS token | Alibaba Cloud - Alibaba Cloud CLI

Alibaba Cloud CLI authenticates using credentials to call cloud service APIs for managing cloud resources. This topic describes how to select a suitable credential type based on your use case, and how to configure and manage credentials.

Select a credential type

Alibaba Cloud CLI supports multiple credential types. Select the type that best fits your use case.

Credential type	Use case	Supports non-interactive configuration	Configuration
OAuth (Recommended)	Sign in with an Alibaba Cloud account, RAM user, or SSO in a browser. Supports MFA and passkeys. No long-term AccessKey storage required, ensuring high security.	No	Configure OAuth credential
EcsRamRole (Recommended)	When running CLI on an ECS instance, automatically obtains temporary security credentials from the RAM role attached to the instance. No AccessKey configuration or storage required.	Yes	Configure EcsRamRole credential
RamRoleArn (Recommended)	Assume a RAM role to operate resources as the role identity. Suitable for temporary privilege escalation or cross-account access. For example, a RAM user with basic permissions can assume a RAM role with resource management permissions, or access resources across Alibaba Cloud accounts. Uses temporary security credentials (STS token).	Yes	Configure RAM role credential
ChainableRamRoleArn	Use a role chain to assume roles sequentially for cross-account resource access.	Yes	Configure RAM role chain credential
OIDC	Authenticates and assumes a role through an ID token issued by an OIDC (OpenID Connect)-compatible external identity provider. Recommended for ACK/ACS pods with RRSA (RAM Roles for Service Accounts) enabled.	Yes	Configure OIDC credential
CloudSSO	For multi-account enterprises with Cloud SSO and Resource Directory. Uses browser-based sign-in with MFA support, similar to OAuth.	No	Configure CloudSSO credential
External	Calls an external executable program to dynamically obtain a credential (AccessKey or temporary security token). Suitable for custom credential provider scenarios.	Yes	Configure External credential
CredentialsURI	Obtains a temporary security credential (STS token) from an HTTP URI that you provide. Suitable for self-hosted credential distribution services.	No	Configure CredentialsURI credential
StsToken	Manually provide a temporary security credential (STS token). The token must be manually updated after it expires.	Yes	Configure StsToken credential
BearerToken	Uses a bearer token to authenticate Alibaba Cloud API services. Suitable for automated scenarios such as CI/CD.	Yes	Configure bearer token credential
AK (Not Recommended)	Uses a long-term AccessKey of an Alibaba Cloud account or a RAM user for direct authentication. The credential is permanently valid and relatively less secure. If you must use this method, we recommend that you first review the AccessKey best practices.	Yes	Configure AK credential

Note

If you use Cloud Shell, the system automatically configures a temporary credential. The identity is the RAM user or role currently signed in to the console, and the permissions are consistent with that identity. You can run CLI commands without manual configuration.

Configure credentials

Alibaba Cloud CLI supports two credential configuration methods: interactive configuration and non-interactive configuration.

Interactive configuration

Interactive configuration uses a command-line wizard that guides you through credential configuration. The system prompts you to enter each credential parameter in sequence. Suitable for local development environments or first-time configuration.

aliyun configure --mode <AuthenticateMode> --profile <ProfileName>

Example: to create an EcsRamRole credential profile named EcsProfile:

aliyun configure --mode EcsRamRole --profile EcsProfile

The following is a sample interactive session:

Configuring profile 'EcsProfile' in 'EcsRamRole' authenticate mode...
Ecs Ram Role []: ECSAdmin
Default Region Id []: cn-shanghai
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[EcsProfile] ...Done.

Non-interactive configuration

Specify credential configuration parameters directly through command-line arguments without interactive input. Suitable for automation scenarios such as scripts and CI/CD pipelines.

Example: to create an AK credential profile named AkProfile:

Bash

aliyun configure set \
  --profile AkProfile \
  --mode AK \
  --access-key-id  ************ \
  --access-key-secret ************ \
  --region "cn-shanghai"

PowerShell

aliyun configure set `
  --profile AkProfile `
  --mode AK `
  --access-key-id  ************ `
  --access-key-secret  ************ `
  --region "cn-shanghai"

For the configuration parameters supported by each credential type, see the corresponding credential type's detailed configuration page. The following parameters are common to all credential types:

Common parameters	Description
`--profile`, `-p`	The profile name. If not specified, the active profile is used.
`--mode`	The credential type. Examples: `AK`, `EcsRamRole`, and `RamRoleArn`.
`--region`	The default region ID, such as `cn-hangzhou`. Used when no region is specified in an API call.

The Select a credential type table shows which types support non-interactive configuration.

Note

You can create multiple profiles for the same credential type with unique names. For example, create ak-dev and ak-prod AK profiles for development and production.

Verify credential configuration

After the credential is configured, run the following command to verify that the credential is valid:

aliyun sts get-caller-identity

If the credential is configured correctly, the output is similar to the following:

If the authenticated identity is a RAM user:

{
  "AccountId": "173305794806****",
  "Arn": "acs:ram::173305794806****:user/<user-name>",
  "IdentityType": "RAMUser",
  "PrincipalId": "20407046578681****",
  "RequestId": "D012C652-FF76-5101-81B3-45A1DDAC****",
  "UserId": "20407046578681****"
}

If the authenticated identity is a RAM role:

{
  "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****"
}

Note

Successful verification only indicates that authentication is successful. To manage resources, you must also attach the corresponding permission policies to the identity associated with the credential.

Manage credentials

Use aliyun configure subcommands to view, switch, modify, and delete credential profiles.

View configurations

View profile list and active profile

View all configured credentials and their status on the current machine. Use this command to check credential profile summary information, such as profile names and credential types, and to identify the active profile.

aliyun configure list

The following is a sample output. The asterisk (*) marks the active credential profile. The active profile is the default credential and parameter set (such as region and language) used by the CLI. Unless you specify a different profile by using the --profile parameter or an environment variable, all commands use this profile.

Profile      | Credential               | Valid   | Region           | Language
---------    | ------------------       | ------- | ---------------- | --------
default      | AK:***UyLX               | Valid   | cn-shanghai      | en
OAuthProfile | OAuth:fiA5bnZkyw@CN      | Valid   | cn-hangzhou      | en
EcsProfile * | EcsRamRole:ecs-role-name | Valid   | cn-beijing       | zh

View profile details

Run the following command to view the detailed information of a specified credential profile:

aliyun configure get [--profile <ProfileName>] [<SETTING_NAME>...]

SETTING_NAME: The name of the settings to view. You can specify multiple settings at the same time. If not specified, all credential profile information is displayed. If the specified setting does not exist, the command returns no output.

List of available settings

Setting name	Description	Associated field
profile	The profile name.	name
mode	The credential type.	mode
region	The default region ID.	region_id
language	The language for help messages.	language
access-key-id	The AccessKey ID of an Alibaba Cloud account or a RAM user.	access_key_id
access-key-secret	The AccessKey Secret of an Alibaba Cloud account or a RAM user.	access_key_secret
sts-token	The temporary security credential (STS token) of a RAM user or role.	sts_token
sts-region	The region ID where the call is initiated to obtain a temporary security credential for a RAM user or role.	sts_region
ram-role-name	The name of the RAM role.	ram_role_name
ram-role-arn	The ARN of the RAM role.	ram_role_arn
external-id	The external ID for the role.	external_id
role-session-name	The role session name.	ram_session_name
cloud-sso-sign-in-url	The sign-in URL for the Cloud SSO user.	cloud-sso-sign-in-url
cloud-sso-access-config	The access configuration ID for Cloud SSO.	cloud-sso-access-config
cloud-sso-account-id	The UID of the Alibaba Cloud account for Cloud SSO sign-in.	cloud-sso-account-id
oauth-site-type	The site type for OAuth sign-in.	oauth-site-type

Note

The associated configuration field represents the field name in the specified profile's configuration information.

Example 1: View the details of a profile named OAuthProfile:

aliyun configure get --profile OAuthProfile

Output:

{
    "name": "OAuthProfile",
    "mode": "OAuth",
    "access_key_id": "STS.9jYc5erFPDLrwNGWc7Sob2ZRHenhHfz7pw9*************",
    "access_key_secret": "3AcNFz37QykuHEwgzWramXGZaCrM1mDHpG1s7v******",
    "sts_token": "CAIS5gJ1q6Ft5DqyfSjI2KnsKI/Rn5lx846Zd******",
    "region_id": "cn-hangzhou",
    "output_format": "json",
    "language": "zh",
    "sts_expiration": 1776751437,
    "oauth_access_token": "eyJhbGciOiJSUzI1NiIsI*******",
    "oauth_refresh_token": "ALGuHPAmSWxR5ynSsoRXhWpUtsxXHcLpGLnZqVvVXZDkjcbMsMasoshv1MnyRhkTq******",
    "oauth_access_token_expire": 1776751436,
    "oauth_site_type": "CN"
}

Example 2: View only the profile name, credential type, and default language for OAuthProfile:

aliyun configure get --profile OAuthProfile profile mode language

Output:

profile=OAuthProfile
mode=OAuth
language=en

Configuration file location

To manually view or back up the credential configuration file, find it at the following paths:

Operating system	Storage path
Linux / macOS	`~/.aliyun/config.json`
Windows	`C:\Users\<USER_NAME>\.aliyun\config.json`

Switch profiles

Switch the active profile

Switch the specified profile to the active profile. Alibaba Cloud CLI supports the aliyun configure switch command since v3.0.214. After a successful switch, all subsequent requests that do not explicitly specify a credential by using the --profile parameter automatically use this profile.

aliyun configure switch --profile <ProfileName>

Note

Run aliyun configure list to confirm the target profile name before switching.

Example: Switch to a profile named prod:

aliyun configure switch --profile prod

After the switch, run aliyun configure list to confirm the target profile is marked with *.

Use a profile for a single command

Use the --profile parameter in a single command to temporarily specify a profile. This does not affect the active profile.

Example: Use the prod profile to query the list of ECS regions:

aliyun ecs describe-regions --profile prod

Modify a profile

Use aliyun configure set to modify parameter values of an existing profile. You only need to specify the parameters to modify. Unspecified parameters remain unchanged.

aliyun configure set --profile <ProfileName> --<ParameterName> <NewValue>

Common parameters:

--region: Default region
--language: Output language (zh / en)

For detailed parameters, see the documentation of each credential type.

Example: Modify the default region of the default profile:

aliyun configure set --profile default --region cn-shanghai

Note

Modifying a profile automatically sets it as the active profile.

Delete a profile

Run the following command to delete a specified profile:

aliyun configure delete --profile <ProfileName>

Example: Delete a profile named dev:

aliyun configure delete --profile dev

Important

The delete operation is irreversible. If you delete the active profile, the first profile in the list automatically becomes the new active profile.

After the deletion, run the aliyun configure list command to confirm that the profile has been removed from the list.

FAQs

What if I enter incorrect information during interactive configuration?

Use aliyun configure set to modify the corresponding field. You do not need to reconfigure from scratch. Example:

aliyun configure set --profile <ProfileName> --<ParameterName> <CorrectValue>

A CLI command does not use the active profile

The CLI determines the actual profile to use based on the following priority (from highest to lowest). Higher priority overrides lower priority:

The --profile command-line parameter: Applies only to the current command and has the highest precedence.
The ALIBABA_CLOUD_PROFILE environment variable: Applies to all commands in the current terminal session.
The active profile: The profile marked with an * in the output of the aliyun configure list command. This setting is persistent.

If a command result does not match expectations, check whether the --profile parameter or the ALIBABA_CLOUD_PROFILE environment variable is set, as they override the active profile. Run echo $ALIBABA_CLOUD_PROFILE to check whether the environment variable is set.

Error: `load current configuration failed unknown profile default`

Full error message:

ERROR: load current configuration failed unknown profile default, run configure to check

Cause:

All credential profiles have been deleted, which prevents Alibaba Cloud CLI from working properly.

Solution:

Manually delete the config.json file and run the aliyun configure command to reconfigure credentials. For the file location, see Configuration file location. For example, on Linux or macOS, run the following command to delete the file:

rm ~/.aliyun/config.json

Select a credential type

Configure credentials

Interactive configuration

Non-interactive configuration

Bash

PowerShell

Verify credential configuration

Manage credentials

View configurations

View profile list and active profile

View profile details

Configuration file location

Switch profiles

Switch the active profile

Use a profile for a single command

Modify a profile

Delete a profile

FAQs

What if I enter incorrect information during interactive configuration?

A CLI command does not use the active profile

Error: load current configuration failed unknown profile default

Related documents

Error: `load current configuration failed unknown profile default`