Alibaba Cloud CLI:Configure credentials in Alibaba Cloud CLI

Common syntax

You can run the aliyun configure command to configure a credential in interactive mode. Syntax:

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

• Command options:

  • --profile <profileName>: the profile name. If the specified profile exists, it is overwritten. If the specified profile does not exist, a profile with the specified name is created.

    If you do not specify a profile, the current profile is modified. For more information about how to modify the current profile, see the "Set the current profile" section in this topic.

  • --mode <AuthenticateMode>: the credential type. The default value is AK.

• Sample success response:

  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 ..............

Common syntax

You can run the aliyun configure set command to configure a credential in non-interactive mode. Syntax:

aliyun configure set [--profile <profileName>] [--mode <AuthenticateMode>] [--settingName <settingValue>...]

• Command options:

  • --profile <profileName>: the profile name. If the specified profile exists, it is overwritten. If the specified profile does not exist, a profile with the specified name is created.

  • --mode <AuthenticateMode>: the credential type. The default value is AK. For more information about the credential types supported by Alibaba Cloud CLI, see the Credential types section of this topic.

  • --settingName <settingValue>: The information that you need to specify varies based on the credential type. For more information, see the "Credential types" section in this topic and the "Non-interactive mode" section in Profile-related commands.

• After you configure a credential in non-interactive mode, you can run the aliyun configure list or aliyun configure get command to check whether the credential is configured as expected.

• In Alibaba Cloud CLI, AK is the default credential type, which uses an AccessKey pair as the credential. Therefore, you can skip the --mode option when you configure a credential of the AK credential type.

• Options:

  Option	Description	Example
  AccessKey Id	The AccessKey ID that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeyID
  AccessKey Secret	The AccessKey secret that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeySecret
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following examples show how to configure a credential named AkProfile of the AK type.

• Interactive mode

  Configuration command:

  aliyun configure --profile AkProfile

  The following sample response shows the interaction process:

  Example

  Configuring profile 'AkProfile' in 'AK' authenticate mode...
  Access Key Id []: <yourAccessKeyID>
  Access Key Secret []: <yourAccessKeySecret>
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[AkProfile] ...Done.

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile AkProfile \
    --mode AK \
    --access-key-id <yourAccessKeyID> \
    --access-key-secret <yourAccessKeySecret> \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile AkProfile `
    --mode AK `
    --access-key-id <yourAccessKeyID> `
    --access-key-secret <yourAccessKeySecret> `
    --region cn-hangzhou

• Security Token Service (STS) tokens are provided by Alibaba Cloud for temporary access to and management of services. For more information about STS tokens, see What is STS?

• An STS token is valid for a specific period. After an STS token expires, you must obtain another STS token. In Alibaba Cloud CLI, credentials of the StsToken type are not automatically renewed. We recommend that you use the following types of credentials:

  • The following types of credentials can be automatically renewed:

    • RamRoleArn

    • EcsRamRole

    • OIDC

    • ChainableRamRoleArn

    • CloudSSO

  • The following types of credentials can be renewed by developers or external programs:

    • CredentialsURI

    • External

• Options:

  Option	Description	Example
  AccessKey Id	The AccessKey ID that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeyID
  AccessKey Secret	The AccessKey secret that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeySecret
  STS Token	Your STS token. For more information, see AssumeRole.	yourSTSToken
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following examples show how to configure a credential named StsProfile of the StsToken type.

• Interactive mode

  Configuration command:

  aliyun configure --profile StsProfile --mode StsToken

  The following sample response shows the interaction process:

  Sample response

  Configuring profile 'StsProfile' in 'StsToken' authenticate mode...
  Access Key Id []: <yourAccessKeyID>
  Access Key Secret []: <yourAccessKeySecret>
  Sts Token []: <yourSTSToken>
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[StsProfile] ...Done.

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile StsProfile \
    --mode StsToken \
    --access-key-id <yourAccessKeyID> \
    --access-key-secret <yourAccessKeySecret> \
    --sts-token <yourSTSToken> \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile StsProfile `
    --mode StsToken `
    --access-key-id <yourAccessKeyID> `
    --access-key-secret <yourAccessKeySecret> `
    --sts-token <yourSTSToken> `
    --region cn-hangzhou

• To configure a credential of the RamRoleArn type, call the AssumeRole operation of STS to obtain an STS token. You can refer to the following topics to learn more about model warm-up:

  • What is STS?

  • AssumeRole

• Temporary credentials of the RamRoleArn type can be automatically renewed:

• Options:

  Option	Description	Example
  AccessKey Id	The AccessKey ID that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeyID
  AccessKey Secret	The AccessKey secret that is used to create the custom image. For more information, see Create an AccessKey pair for a RAM user.	yourAccessKeySecret
  STS Region	The region from which the request for the STS token is initiated. For more information about the regions in which STS is supported, see Endpoints.	cn-hangzhou
  Ram Role Arn	The ARN of the RAM role to be assumed. The trusted entity of the RAM role is an Alibaba Cloud account. For more information, see Create a RAM role for a trusted Alibaba Cloud account or CreateRole. You can view the ARNs of RAM roles by using the RAM console or by calling API operations. The following code shows how to register Short Video SDK of different versions. For more information about how to view the ARN in the RAM console, see How do I find the ARN of the RAM role? For more information about how to view the ARN by calling operations, see ListRoles or GetRole.	acs:ram::012345678910****:role/Alice
  Role Session Name	The custom name of the role session. Set this parameter based on your business requirements. In most cases, you can set this parameter to the identity of the user who calls the operation. For example, specify a username. You can specify RoleSessionName to identify API callers that assume the same RAM role in ActionTrail logs. This allows you to track the users that perform the operations. The name must be 2 to 64 characters in length, and can contain letters, digits, and the following special characters: . @ - _.	alice
  External Id	The external ID of the RAM role. The value of this parameter is provided by an external party and is used to prevent the confused deputy issue. For more information, see Use external IDs to prevent the confused deputy issue. The ID must be 2 to 1,224 characters in length and can contain letters, digits, and the following special characters: = , . @ : / - _. The regular expression for this parameter is [\w+=,.@:\/-]*.	abcd1234
  Expired Seconds	The validity period of the credential. Unit: seconds. The default value is 900. The maximum value is the value of MaxSessionDuration.	900
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following examples show how to configure a credential named RamRoleArnProfile of the RamRoleArn type.

• Interactive mode

  Configuration command:

  aliyun configure --profile RamRoleArnProfile --mode RamRoleArn

  The following sample response shows the interaction process:

  Sample response

  Configuring profile 'RamRoleArnProfile' in 'RamRoleArn' authenticate mode...
  Access Key Id []: <yourAccessKeyID>
  Access Key Secret []: <yourAccessKeySecret>
  Sts Region []: cn-hangzhou
  Ram Role Arn []: acs:ram::012345678910****:role/Alice
  Role Session Name []: alice
  External ID []: abcd1234
  Expired Seconds [900]: 900
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[RamRoleArnProfile] ...Done.

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile RamRoleArnProfile \
    --mode RamRoleArn \
    --access-key-id <yourAccessKeyID> \
    --access-key-secret <yourAccessKeySecret> \
    --sts-region cn-hangzhou
    --ram-role-arn acs:ram::012345678910****:role/Alice \
    --role-session-name alice \
    --external-id abcd1234 \
    --expired-seconds 900 \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile RamRoleArnProfile `
    --mode RamRoleArn `
    --access-key-id <yourAccessKeyID> `
    --access-key-secret <yourAccessKeySecret> `
    --sts-region cn-hangzhou `
    --ram-role-arn acs:ram::012345678910****:role/Alice `
    --role-session-name alice `
    --external-id abcd1234 `
    --expired-seconds 900 `
    --region cn-hangzhou

• Credentials of the EcsRamRole type do not require an AccessKey pair. If you use Alibaba Cloud CLI to perform API operations on an ECS instance or an ECI, you can access the metadata service of the instance to obtain an STS token. This minimizes the risk of AccessKey leaks.

• Temporary credentials of the EcsRamRole type can be automatically renewed.

• The metadata server supports access in normal mode (IMDSv1) and security hardening mode (IMDSv2). By default, Alibaba Cloud CLI obtains access credentials from the metadata server in security hardening mode. If an exception occurs in the security hardening mode, you can configure the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable to specify an exception handling logic. Sample configurations:

  • false (default): The Credentials tool continues to obtain the access credential in normal mode.

  • true: The exception is thrown and Alibaba Cloud CLI continues to obtain the access credential in security hardening mode.

  The configurations for the metadata server determine whether the server supports the security hardening mode (IMDSv2).

  For more information about how to configure environment variables, see Configure environment variables in Linux, macOS, and Windows.

• Options:

  Option	Description	Example
  Ecs Ram Role	The name of the RAM role to be attached to the ECS instance. If you do not specify a RAM role, the program automatically accesses the metadata service of the ECS instance to obtain the RoleName information, which can be used to obtain the credential. Two requests must be sent during this process.	ECSAdmin
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following examples show how to configure a credential namedEcsRamRole of the EcsRamRole type.

• Interactive mode

  Configuration command:

  aliyun configure --profile EcsProfile --mode EcsRamRole

  The following sample response shows the interaction process:

  Sample response

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

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile EcsProfile \
    --mode EcsRamRole \
    --ram-role-name ECSAdmin \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile EcsProfile `
    --mode EcsRamRole `
    --ram-role-name ECSAdmin `
    --region cn-hangzhou

• Alibaba Cloud CLI can obtain an external credential by running a command of an external program.

• You can manually renew external credentials.

• Options:

  Option	Description	Example
  Process Command	The command for running external programs. You can configure the external program to return an AccessKey pair or an STS token, which are both static credentials.	acs-sso login --profile sso
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

• Sample credentials returned from the external program:

  AccessKey

  {
    "mode": "AK",
    "access_key_id": "<yourAccessKeyID>",
    "access_key_secret": "<yourAccessKeySecret>"
  }

  STS Token

  {
    "mode": "StsToken",
    "access_key_id": "<yourAccessKeyID>",
    "access_key_secret": "<yourAccessKeySecret>",
    "sts_token": "<yourSTSToken>"
  }

Configuration example

The following examples show how to configure a credential named ExternalProfile of the External type.

• Interactive mode

  Configuration command:

  aliyun configure --profile ExternalProfile --mode External

  The following sample response shows the interaction process:

  Example

  Configuring profile 'ExternalProfile' in 'External' authenticate mode...
  Process Command []: acs-sso login --profile sso
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[ExternalProfile] ...Done.

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile ExternalProfile \
    --mode External \
    --process-command acs-sso login --profile sso \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile ExternalProfile `
    --mode External `
    --process-command acs-sso login --profile sso `
    --region cn-hangzhou

• The ChainableRamRoleArn credential type allows you to use chainable role assumption to obtain credentials. To use a credential of this type, Alibaba Cloud CLI obtains an intermediate credential, such as an AccessKey pair or an STS token, from the source credential, assumes a role by using the intermediate credential, and then obtains the final credential, which is an STS token.

• Credentials of the ChainableRamRoleArn type can be automatically renewed.

• Options:

  Option	Description	Example
  Source Profile	The name of the source profile. Before you configure a credential of the ChainableRamRoleArn type, you must configure a source profile. For more information, see the following configuration example.	RamRoleArnProfile
  STS Region	The region from which the request for the STS token is initiated. For more information about the regions in which STS is supported, see Endpoints.	cn-hangzhou
  Ram Role Arn	The ARN of the RAM role to be assumed. The trusted entity of the RAM role is an Apsara Stack tenant account. For more information, see Create a RAM role for a trusted Alibaba Cloud account or CreateRole. You can view the ARNs of RAM roles by using the RAM console or by calling API operations. The following code shows how to register Short Video SDK of different versions. For more information about how to view the ARN in the RAM console, see How do I find the ARN of the RAM role? For more information about how to view the ARN by calling operations, see ListRoles or GetRole.	acs:ram::012345678910****:role/Alice
  Role Session Name	The custom name of the role session. Set this parameter based on your business requirements. In most cases, you can set this parameter to the identity of the user who calls the operation. For example, specify a username. You can specify RoleSessionName to identify API callers that assume the same RAM role in ActionTrail logs. This allows you to track the users that perform the operations. The name must be 2 to 64 characters in length, and can contain letters, digits, and the following special characters: . @ - _.	alice
  External Id	The external ID of the RAM role. The value of this parameter is provided by an external party and is used to prevent the confused deputy issue. For more information, see Use external IDs to prevent the confused deputy issue. The ID must be 2 to 1,224 characters in length, and can contain letters, digits, and the following special characters: = , . @ : / - _. The regular expression for this parameter is [\w+=,.@:\/-]*.	abcd1234
  Expired Seconds	The validity period of the access token. Unit: seconds. The default value is 900. The maximum value is the value of MaxSessionDuration.	900
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following example shows how to configure a credential named ChainableProfile of the ChainableRamRoleArn type. In this example, the source profile is named RamRoleArnProfile and of the RamRoleArn credential type.

• Interactive mode

  1. Configure the source profile RamRoleArnProfile. For more information, see the configuration examples in the "RamRoleArn" section of this topic.

  2. Run the following command to configure the ChainableProfile credential of the ChainableRamRoleArn type.

     aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn

     The following sample response shows the interaction process. Specify the source profile by setting the Source Profile parameter to RamRoleArnProfile.

     Example

     Configuring profile 'ChainableProfile' in 'ChainableRamRoleArn' authenticate mode...
     Source Profile []: RamRoleArnProfile
     Sts Region []: cn-hangzhou
     Ram Role Arn []: acs:ram::012345678910****:role/Alice
     Role Session Name []: alice
     External ID []: abcd1234
     Expired Seconds [900]: 900
     Default Region Id []: cn-hangzhou
     Default Output Format [json]: json (Only support json)
     Default Language [zh|en] en: en
     Saving profile[ChainableProfile] ...Done.

• You cannot configure a credential of the ChainableRamRoleArn type in non-interactive mode.

• Credentials of the CredentialsURI type obtain Security Token Service (STS) tokens for API calls by using the URI provided by you.

• You can also manually renew credentials of the CredentialsURI type.

• Options:

  Option	Description	Example
  CredentialsURI	The local or remote URI. If the HTTP 200 status code cannot be returned from the specified address, or the response structure is not in the expected format, Alibaba Cloud CLI determines that the request fails.	http://credentials.uri/
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

• Sample response structure from the URI:

  {
    "Code": "Success",
    "AccessKeyId": "<yourAccessKeyID>",
    "AccessKeySecret": "<yourAccessKeySecret>",
    "SecurityToken": "<yourSTSToken>",
    "Expiration": "2006-01-02T15:04:05Z" // utc time
  }

Configuration example

The following examples show how to configure a credential named URIProfile of the CredentialsURI type.

• Interactive mode

  Configuration command:

  aliyun configure --profile URIProfile --mode CredentialsURI

  The following sample response shows the interaction process:

  Example

  Configuring profile 'URIProfile' in 'CredentialsURI' authenticate mode...
  Credentials URI []: http://credentials.uri/
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[URIProfile] ...Done.

• You cannot configure a credential of the CredentialsURI type in non-interactive mode.

• To configure a credential of the OIDC type, call the AssumeRoleWithOIDC operation of STS to obtain an STS token. For more information about the RRSA feature, see Use RRSA to authorize different pods to access different cloud services.

• Credentials of the OIDC type can be automatically renewed.

• Options:

  Option	Description	Example
  OIDCProviderARN	The ARN of the OIDC IdP. You can view the ARN of an OIDC IdP in the RAM console or by calling an API operation. For more information about how to view the ARN of an OIDC IdP in the RAM console, see Manage an OIDC IdP. For more information about how to view the ARN by calling operations, see GetOIDCProvider or ListOICProviders.	acs:ram::012345678910****:oidc-provider/TestOidcIdp
  OIDCTokenFile	The file path of the OIDC token. An OIDC token is issued by an external IdP.	/path/to/oidctoken
  Ram Role Arn	The ARN of the RAM role to be assumed. You can view the ARNs of RAM roles by using the RAM console or by calling API operations. The following code shows how to register Short Video SDK of different versions. For more information about how to view the ARN in the RAM console, see How do I find the ARN of the RAM role? For more information about how to view the ARN by calling operations, see ListRoles or GetRole.	acs:ram::012345678910****:role/Alice
  Role Session Name	The custom name of the role session. Set this parameter based on your business requirements. In most cases, you can set this parameter to the identity of the user who calls the operation. For example, specify a username. You can specify RoleSessionName to identify API callers that assume the same RAM role in ActionTrail logs. This allows you to track the users that perform the operations. The name must be 2 to 64 characters in length, and can contain letters, digits, and the following special characters: . @ - _.	alice
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Configuration example

The following examples show how to configure a credential named OIDC_Profile of the OIDC type.

• Interactive mode

  Configuration command:

  aliyun configure --profile OIDC_Profile --mode OIDC

  The following sample response shows the interaction process:

  Example

  Configuring profile 'OIDC_Profile' in 'OIDC' authenticate mode...
  OIDC Provider ARN []: acs:ram::012345678910****:oidc-provider/TestOidcIdp
  OIDC Token File []: /path/to/oidctoken
  RAM Role ARN []: acs:ram::012345678910****:role/Alice
  Role Session Name []: alice
  Default Region Id []: cn-hangzhou
  Default Output Format [json]: json (Only support json)
  Default Language [zh|en] en: en
  Saving profile[OIDC_Profile] ...Done.

• Non-interactive mode

  Configuration command:

  Bash

  aliyun configure set \
    --profile OIDC_Profile \
    --mode OIDC \
    --oidc-provider-arn acs:ram::012345678910****:oidc-provider/TestOidcIdp \
    --oidc-token-file /path/to/oidctoken \
    --ram-role-arn acs:ram::012345678910****:role/Alice \
    --role-session-name alice \
    --region cn-hangzhou

  PowerShell

  aliyun configure set `
    --profile OIDC_Profile `
    --mode OIDC `
    --oidc-provider-arn acs:ram::012345678910****:oidc-provider/TestOidcIdp `
    --oidc-token-file /path/to/oidctoken `
    --ram-role-arn acs:ram::012345678910****:role/Alice `
    --role-session-name alice `
    --region cn-hangzhou

• CloudSSO is integrated with Alibaba Cloud Resource Directory to provide centralized multi-account identity management and access control. After you assign the access permissions on an account in your resource directory to a Cloud SSO user or user group by using an access configuration, the access configuration is provisioned for the account and serves as a RAM role of the account. CloudSSO assumes the RAM role to obtain an STS token for calling API operations. This reduces the risk of AccessKey pair leaks.

• Temporary credentials of the CloudSSO type can be automatically renewed:

• Options:

  Option	Description	Example
  signinUrl	The logon URL. To obtain the URL, log on to the CloudSSO console, go to the Overview page, and then find the User Logon URL section on the right.	https://signin-******.alibabacloudsso.com/device/login
  Region Id	The default region. Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.	cn-hangzhou

Procedure

1. Run the following command to configure information about access to CloudSSO: You can specify multiple profiles and specify a specific profile to quickly switch between accounts and access configurations.

   aliyun configure --profile sso --mode CloudSSO

2. Specify a URL for the signinUrl option to configure the URL that is used to log on to the CloudSSO user portal.

   aliyun configure --profile sso --mode CloudSSO
   CloudSSO Sign In Url []: https://signin-******.alibabacloudsso.com/device/login

3. In the browser that appears, log on to the user portal. After you log on to the user portal, close the browser.

   If no browsers appear, copy the logon URL and user code that are provided in the CLI to log on to the user portal.

   Example:

   If the browser does not open automatically, use the following URL to complete the login process:
   
   SignIn url: https://signin-****.alibabacloudsso.com/device/code
   User code: *********

4. The CLI prompts that the logon succeeds and outputs the username of the resource directory account that you can access. Enter the number of the account that you want to access.

   Now you can login to your account with SSO configuration in the browser.
   You have successfully logged in.
   Please choose an account:
   1. <RD Management Account>
   2. AccountName
   Please input the account number: 1

5. The CLI outputs the available access configurations. Enter the number of the access configuration that you want to use.

   Please choose an access configuration:
   1. AccessConfiguration1
   2. AccessConfiguration2
   Please input the access configuration number: 2

6. Specify the default region.

   Default Region Id []: cn-hangzhou

7. After the configuration is successful, the Configure Done message and a welcome message are displayed.