All Products
Search

This Product

    Alibaba Cloud CLI:Configure identity credentials

    Document Center

    Alibaba Cloud CLI:Configure identity credentials

    Last Updated:Jul 10, 2024

    Before you use Alibaba Cloud CLI, you must configure the information that is required to call Alibaba Cloud resources. This information includes the identity credential, region, and language. Alibaba Cloud CLI automatically generates and uses a credential configuration named default when it runs for the first time. You can also configure and use your custom credential.

    Configure the storage location

    A configuration file, referred to as a profile, is a set of configuration items and has a customizable name. All configuration items are stored in the JSON format within the profiles configuration collection in the config.json file. The config.json file is located in the .aliyun folder within your personal user directory. The location of the personal user directory varies with the operating system.

    • Windows: C:\Users\USERNAME\.aliyun

    • Linux or macOS: ~/.aliyun

    Credential configuration methods

    Alibaba Cloud CLI provides two configuration methods: interactive configuration and non-interactive configuration. You can select a configuration method based on your business requirements.

    • Interactive configuration provides a configuration guide for users to configure identity credentials in Alibaba Cloud CLI at a low learning cost. We recommend that you use this method if you are a beginner, are unfamiliar with CLI operations, or occasionally configure a credential.

    • Non-interactive configuration allows you to specify configuration items directly by using parameters in commands or environment variables. This method offers high flexibility and efficiency. We recommend that you use this method if you want to manage and use Alibaba Cloud CLI by using scripts, automated deployment tools, or configuration management tools.

    Interactive configuration

    General syntax

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

    • --mode: specifies the credential type. For more information about credential types supported, see the Identity credential types section of this topic.

    • --profile: specifies the profile name. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.

    • Make sure that you specify valid AccessKey information. Invalid information may cause accidental operations or API call failures.

    • After you configure a credential by using the interactive method, the following information is displayed if the configuration is valid:

      Complete response message

      Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

    Non-interactive configuration

    General syntax

    Non-interactive configuration uses the set sub-command of the configure command to configure credentials. The following command format is used:

    aliyun configure set [--settingName <settingValue>]... --profile <profileName> --region <regionId>
    Note

    The credential options are required for credential configuration. When you configure a specific type of credential, you need to only configure the options required for that credential type.

    • The following list describes the common options, which apply to all credential types:

      • --profile: required. Specifies the profile name. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.

      • --region: required. Specifies the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • --language: specifies the language of Alibaba Cloud CLI. Default value: en.

      • --mode: specifies the credential type. Default value: AK.

    • Usage notes

      • Make sure that you specify valid AccessKey information. Invalid information may cause accidental operations or API call failures.

      • After you configure a credential by using the non-interactive method, run the list or get command to check whether the credential is created. For more information, see Other configure command operations.

    Identity credential types

    AccessKey credentials

    Description

      Important

      To ensure the security of your Alibaba Cloud account, we recommend that you create a Resource Access Management (RAM) user for calling API operations and create an AccessKey pair for the RAM user. For more information about how to use an AccessKey pair in a secure manner, see Credential security solutions.

    • In Alibaba Cloud CLI, the AccessKey credential type is named AK and is the default credential type. Therefore, you can omit the --mode option when you configure an AccessKey credential.

    • Required options:

    Configuration examples

    The following examples show how to configure an AccessKey credential named akProfile.

    • Interactive configuration

      Run the following command:

      aliyun configure --profile akProfile

      The following sample response shows the interaction process:

      Configuring profile 'akProfile' in '' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en:
Saving profile[akProfile] ...Done.

    • Non-interactive configuration

      Run the set sub-command of the configure command:

      aliyun configure set
  --profile akProfile
  --mode AK
  --region cn-hangzhou
  --access-key-id AccessKeyId
  --access-key-secret AccessKeySecret

    STS token credentials

    Description

    Important

    Security Token Service (STS) tokens are provided by Alibaba Cloud for temporary access to and management of services. An STS token is valid for a specified period. After an STS token expires, you must obtain another STS token. For more information about STS tokens, see What is STS?

    • When you configure a credential of the StsToken type, you must set the --mode option to StsToken.

    • Required options:

      • AccessKey Id: specifies your AccessKey ID. For more information, see Create an AccessKey pair.

      • AccessKey Secret: specifies your AccessKey secret. For more information, see Create an AccessKey pair.

      • Region Id: specifies the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • STS Token: specifies the information required for STS token authentication. For more information, see AssumeRole.

    Configuration examples

    The following examples show how to configure an STS token credential named stsTokenProfile.

    • Interactive configuration

      Run the following command:

      aliyun configure --profile stsTokenProfile --mode StsToken

      The following sample response shows the interaction process:

      Configuring profile 'stsTokenProfile' in 'StsToken' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Sts Token []: StsToken
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en:
Saving profile[stsTokenProfile] ...Done.

    • Non-interactive configuration

      Run the set sub-command of the configure command:

      aliyun configure set
  --profile stsTokenProfile
  --mode StsToken
  --region cn-hangzhou
  --access-key-id AccessKeyId
  --access-key-secret AccessKeySecret
  --sts-token StsToken

    RamRoleArn credentials

    Description

    • When you configure a credential of the RamRoleArn type, you must set the --mode option to RamRoleArn.

    • Required options:

      • AccessKey Id: specifies your AccessKey ID. For more information, see Create an AccessKey pair.

      • AccessKey Secret: specifies your AccessKey secret. For more information, see Create an AccessKey pair.

      • Region Id: specifies the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • Region Id: specifies the information required for RamRoleArn authentication. For more information about how to create a RAM role, see Create a RAM role. After the RAM role is created, you can view the Alibaba Cloud Resource Name (ARN) of the RAM role in the RAM console.

      • RoleSessionName: specifies the session name of the RAM role. For more information, see Assume a RAM role.

    Configuration examples

    The following examples show how to configure a RamRoleArn credential named ramRoleArnProfile.

    • Interactive configuration

      Run the following command:

      aliyun configure --profile ramRoleArnProfile --mode RamRoleArn

      The following sample response shows the interaction process:

      Configuring profile 'ramRoleArnProfile' in 'RamRoleArn' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Ram Role Arn []: RamRoleArn
Role Session Name []: RoleSessionName
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en:
Saving profile[ramRoleArnProfile] ...Done.

    • Non-interactive configuration

      Run the set sub-command of the configure command:

      aliyun configure set
  --profile ramRoleArnProfile
  --mode RamRoleArn
  --region cn-hangzhou
  --access-key-id AccessKeyId
  --access-key-secret AccessKeySecret
  --ram-role-arn RamRoleArn
  --role-session-name RoleSessionName

    EcsRamRole credentials

    Description

    • When you configure a credential of the EcsRamRole type to access Alibaba Cloud, you must set the --mode option to EcsRamRole.

    • You can use this method when you use Alibaba Cloud CLI in Elastic Compute Service (ECS) instances. In this case, you need to only configure a role without specifying an AccessKey pair.

    • Required options:

    Configuration examples

    The following examples show how to configure an EcsRamRole credential named ecsRamRoleProfile.

    • Interactive configuration

      Run the following command:

      aliyun configure --profile ecsRamRoleProfile --mode EcsRamRole

      The following sample response shows the interaction process:

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

    • Non-interactive configuration

      Run the set sub-command of the configure command:

      aliyun configure set
  --profile ecsRamRoleProfile
  --mode EcsRamRole
  --ram-role-name RoleName
  --region cn-hangzhou

    Specify a credential configuration

    • If no identity credential configuration is specified, the credential configuration named default is used.

    • You can use either of the following methods to specify a credential configuration.

      Specify the default credential configuration

      After you specify the default credential configuration, you do not need to repeatedly specify a profile when you use Alibaba Cloud CLI. You can specify the --profile option to override the default credential configuration.

      You can use either of the following methods to specify a credential configuration:

      • Run the set sub-command of the configure command to set an existing credential configuration as the default configuration. For more information, see Specify the default credential configuration.

      • Change the value of the current element in the config.json file to the specified credential configuration name.

      Specify a credential configuration by using the -profile option in commands

      Add the --profile profileName option to your command to use the specified credential configuration.

      Example: Call the DescribeInstances API operation by using a credential named exampleProfile to obtain the information about all ECS instances that the credential can access. 

      aliyun ecs DescribeInstances --profile exampleProfile