Resource Access Management:Configure OAuth authentication for Alibaba Cloud CLI

Overview

The Alibaba Cloud CLI version 3.0.299 or later supports OAuth as a credential type. This method uses a browser logon based on the OAuth 2.0 Proof Key for Code Exchange (PKCE) flow to obtain a token that represents the user's identity for accessing Alibaba Cloud resources.

OAuth authentication has the following advantages over traditional AccessKey pair authentication:

• Improved security: Eliminates the need to store plaintext AccessKey pairs in local configuration files. This reduces the risk of credential leakage.

• Integration with existing authentication systems: Works with logon methods such as passkeys, multi-factor authentication (MFA), and single sign-on (SSO), including user-based SSO and role-based SSO.

Prerequisites

Before you begin, make sure the following requirements are met:

• CLI version: You must have Alibaba Cloud CLI version 3.0.299 or later installed.

• Administrator permissions: The initial setup requires a RAM administrator with the AliyunRAMFullAccess policy attached.

• Environment requirements: The device running the Alibaba Cloud CLI must have a graphical user interface (GUI) and a web browser. This authentication method does not work in headless environments, such as a remote Linux server accessed via Secure Shell (SSH), because it requires a browser to complete the login flow.

Procedure

1. Create a CLI application in Resource Access Management (RAM) for your Alibaba Cloud account in one of the following two ways:

   • Using the Alibaba Cloud CLI: A RAM administrator initiates the first OAuth logon from the CLI. After completing authentication and granting consent in the browser, the system automatically creates an official OAuth application named official-cli.

   • Using the RAM console: A RAM administrator manually installs the official-cli application in the RAM console. Using this method, you do not need to call the AdminConsent operation.

2. Assign RAM identities. After the CLI application is created, a RAM administrator must assign identities, such as RAM users or RAM roles, to the application. Only assigned identities can use this method to log on to the CLI.

3. Authorize and log on to the CLI. The assigned RAM user runs the CLI configuration command on their device. The CLI automatically opens a browser. After the user logs on and grants authorization in the browser, the CLI can obtain the token and complete the authentication.

Step 1: Create a CLI application

This step must be performed by a RAM administrator attached with the AliyunRAMFullAccess policy.

Step 2: Assign RAM identities to the application

After creating the application, you must specify which RAM users or RAM roles are allowed to use it for CLI authentication. If you created the CLI application using the Alibaba Cloud CLI, you are prompted to assign identities immediately after successful authorization. If you installed the application in the RAM console, skip step 1 below.

1. Navigate to the official-cli application's details page.

   • If you just completed Method 1, your browser may show a success page with a Go now button to take you to the page.

     

   • Alternatively, log on to the RAM console and choose Integrations > OAuth Preview. On the Third-party Application tab, click the official-cli application.  

2. Click the Assignments tab, and click Create Assignment.

3. In the Create Assignment panel, select the RAM identities (RAM users or RAM roles) that you want to grant CLI access to, and click OK.  

   

   Note

   You can only assign RAM users and RAM roles. Assigning user groups is not supported.

Step 3: Authorize and log on to the CLI

Any user who has been assigned to the official-cli application by an administrator can follow these steps to configure their local CLI.

1. Run the following command to start the configuration process:

   aliyun configure --profile OAuthProfile --mode OAuth

2. When prompted, select the login site (CN or INTL) that corresponds to your account.

3. Your default web browser will open to an Alibaba Cloud login page. Log on with your assigned RAM user identity.

4. If this is your first time logging in with this method, you will be prompted to grant permissions to the CLI. On the User Authorization page, click Authorize.

   

   Important

   User authorization is a one-time action for your first logon and is not required for subsequent logons, unless the official-cli application is deleted from RAM.

   You can also use this method to authenticate as a RAM role. Before running aliyun configure, first assume the role in your browser session. You can do this in one of two ways:

   • SSO: Log in to the Alibaba Cloud console via your Identity Provider (IdP) using role-based SSO.

   • Console switch role: Log in to the console as a RAM user, and switch to your target RAM role.

   Once you have assumed the role in your browser, run aliyun configure --profile OAuthProfile --mode OAuth in your terminal. The CLI will use your active role session to complete the authentication.

   Note

   Administrator consent and user authorization are two different, required steps.

   • Administrator consent: A one-time action by an admin to install the official-cli application in the account.

   • User authorization: A one-time action by each user to allow the CLI to perform operations on their behalf.

5. Set the default region. After the authorization is successful, you will be prompted to set a default region.

   Default Region Id []: cn-hangzhou

   Note

   Some cloud services do not support cross-region access. We recommend that you specify the region of your resources.

6. The terminal displays Configure Done and a welcome message, which indicates that the configuration is successful.

7. (Optional) Verify your identity. To confirm that you are logged in with the correct identity, run the following command:

   aliyun sts GetCallerIdentity --profile OAuthProfile

Troubleshooting

References

• Install Alibaba Cloud CLI in Linux

• Update Alibaba Cloud CLI

• Configure Alibaba Cloud CLI credentials