阿里雲CLI支援多種憑證類型以適配不同情境，通過合理選擇和配置憑證類型可有效提升安全性與管理效率。 - Alibaba Cloud CLI

阿里雲 CLI 通過身份憑證完成認證，才能調用雲端服務 API 操作雲資源。本文介紹如何根據使用情境選擇合適的憑證類型，以及如何配置和管理憑證。

選擇憑證類型

阿里雲 CLI 支援多種憑證類型，請根據使用情境選擇對應類型。

憑證類型	適用情境	支援非互動式配置	詳細配置
OAuth（推薦）	在瀏覽器中以阿里雲帳號、RAM 使用者或 SSO 登入，支援 MFA 和通行密鑰（Passkey）。無需儲存長期存取金鑰（AccessKey），安全性高。	否	配置 OAuth 憑證
EcsRamRole（推薦）	在 ECS 執行個體內運行 CLI 時，通過執行個體綁定的 RAM 角色自動擷取臨時安全憑證，無需配置或儲存長期存取金鑰（AccessKey）。	是	配置 EcsRamRole 憑證
RamRoleArn（推薦）	扮演 RAM 角色並以角色身份操作資源。適合臨時提權或跨帳號訪問情境。例如：以基礎許可權 RAM 使用者扮演具備資源系統管理權限的 RAM 角色，或跨阿里雲帳號訪問資源。使用臨時安全憑證STS Token。	是	配置 RAM 角色憑證
ChainableRamRoleArn	鏈式角色扮演（角色鏈），適用於需要跨多個帳號進行資源訪問的情境。	是	配置 RAM 角色鏈憑證
OIDC	通過相容 OIDC（OpenID Connect）協議的外部身份供應商頒發的 ID Token 進行身份認證和角色扮演。建議在開啟了 RRSA（RAM Roles for Service Accounts）的 ACK/ACS Pod 中使用。	是	配置 OIDC 憑證
CloudSSO	適合開啟了雲 SSO 和資來源目錄的多帳號企業環境。與 OAuth 類似，通過瀏覽器登入認證，屬於互動式認證方式，支援 MFA。	否	配置 CloudSSO 憑證
External	調用外部可執行程式動態擷取憑證（AccessKey 或臨時安全性權杖），適用於自訂憑證提供者的情境。	是	配置 External 憑證
CredentialsURI	通過您提供的HTTP URI 地址擷取臨時安全憑證 STS Token，適用於自建憑證分發服務的情境。	否	配置 CredentialsURI 憑證
StsToken	手動提供臨時安全憑證 STS Token，令牌到期後需手動更新。	是	配置 StsToken 憑證
BearerToken	使用 Bearer Token 認證阿里雲 API 服務，適用於CI/CD等自動化情境。	是	配置 BearerToken 憑證
AK（不推薦）	使用阿里雲帳號或 RAM 使用者的長期存取金鑰（AccessKey）直接認證。憑證永久有效，安全性相對較低。如確實要使用，建議先參考AccessKey最佳實務。	是	配置 AK 憑證

說明

如果使用雲命令列（Cloud Shell），系統會自動設定臨時憑證。身份為當前登入控制台的RAM使用者或角色，許可權與該身份一致，無需手動設定即可直接執行 CLI 命令。

配置憑證

阿里雲 CLI 支援兩種憑證配置方式：互動式配置、非互動式配置。

互動式配置

互動式配置通過命令列嚮導引導您完成憑證配置。運行命令後，系統會依次提示您輸入各項憑證參數。適合本地開發環境或首次配置。

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

樣本：建立一個名為 EcsProfile 的 EcsRamRole 憑證配置：

aliyun configure --mode EcsRamRole --profile EcsProfile

互動過程樣本：

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.

非互動式配置

通過命令列參數直接指定各項憑證配置參數資訊，無需互動輸入，適用於自動化情境（如指令碼、CI/CD 流水線）。

樣本：建立一個名為 AkProfile 的 AK 憑證配置：

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"

各憑證類型支援的配置參數請參見對應憑證類型的詳細配置文檔。以下參數在所有憑證類型中通用：

憑證配置通用參數	說明
`--profile`，`-p`	配置名稱。未指定時，使用當前啟用配置。
`--mode`	憑證類型，例如 `AK`、`EcsRamRole`、`RamRoleArn` 等。
`--region`	預設地區 ID，例如 `cn-hangzhou`。執行 API 呼叫時若未顯式指定地區，則使用此預設值。

各憑證類型是否支援非互動式配置，見上方選擇憑證類型。

說明

同一種憑證類型可配置多份，配置名稱不同即可。例如，可建立 ak-dev 和 ak-prod 兩份 AK 憑證配置，分別用於開發和生產環境。

驗證憑證配置

憑證配置完成後，運行以下命令驗證憑證是否有效：

aliyun sts get-caller-identity

憑證配置正確時，輸出類似如下：

如當前通過認證的身份為RAM使用者：

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

如當前通過認證的身份為RAM角色：

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

說明

驗證通過僅代表身份認證成功。要操作資源，還需為憑證關聯的身份授予相應權限原則。

管理憑證

通過 aliyun configure 子命令可對已有憑證配置進行查看、切換、修改和刪除操作。

查看配置

查看配置列表與當前啟用配置

查看當前機器上所有已配置的憑證及其狀態。可用於確認憑證配置概要資訊（如配置名稱、憑證類型等），以及哪個是當前的啟用配置。

aliyun configure list

命令輸出樣本如下，帶 * 標記的為當前啟用的憑證配置。啟用配置即 CLI 執行命令時預設使用的憑證和參數（如地區、語言），未通過 --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

查看指定配置詳情

運行以下命令查看指定憑證配置的詳細資料：

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

SETTING_NAME：指定要查看的設定項名稱，可同時指定多項。未指定時顯示全部憑證配置資訊。若指定的設定項不存在，命令不返回資訊。

可查看設定項列表

設定項名稱	說明	關聯配置欄位
profile	配置名稱。	name
mode	憑證類型。	mode
region	預設地區ID。	region_id
language	協助資訊語言。	language
access-key-id	阿里雲帳號或 RAM 使用者的AccessKey ID。	access_key_id
access-key-secret	阿里雲帳號或 RAM 使用者的AccessKey Secret。	access_key_secret
sts-token	RAM使用者或角色的臨時身份憑證STS Token。	sts_token
sts-region	RAM使用者或角色擷取臨時身份憑證時發起調用的地區ID。	sts_region
ram-role-name	RAM角色名稱。	ram_role_name
ram-role-arn	RAM角色ARN。	ram_role_arn
external-id	角色外部ID。	external_id
role-session-name	角色會話名稱。	ram_session_name
cloud-sso-sign-in-url	雲SSO使用者登入地址。	cloud-sso-sign-in-url
cloud-sso-access-config	雲SSO訪問配置ID。	cloud-sso-access-config
cloud-sso-account-id	雲SSO登入雲帳號UID。	cloud-sso-account-id
oauth-site-type	OAuth登入網站類型。	oauth-site-type

說明

關聯配置欄位代表指定profile配置資訊中的欄位名。

樣本一：查看名為 OAuthProfile 的配置詳情：

aliyun configure get --profile OAuthProfile

輸出：

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

樣本二：僅查看 OAuthProfile 的配置名稱、憑證類型及預設語言：

aliyun configure get --profile OAuthProfile profile mode language

輸出：

profile=OAuthProfile
mode=OAuth
language=en

憑證配置儲存位置

如需手動查看或備份憑證設定檔，可在以下路徑找到：

作業系統	儲存路徑
Linux / macOS	`~/.aliyun/config.json`
Windows	`C:\Users\<USER_NAME>\.aliyun\config.json`

切換配置

永久切換啟用配置

將指定配置切換為當前啟用的配置。阿里雲 CLI 自 v3.0.214 版本起支援 aliyun configure switch 命令。切換成功後，後續所有未顯式指定憑證（使用--profile參數）的請求均自動使用該配置。

aliyun configure switch --profile <ProfileName>

說明

切換前，可使用 aliyun configure list 確認目標配置的名稱。

樣本：切換到名為 prod 的配置：

aliyun configure switch --profile prod

切換完成後，運行 aliyun configure list 確認目標配置已標記 *。

單次使用指定配置

在單條命令中通過 --profile 參數臨時指定配置，不影響當前啟用的配置。

樣本：使用 prod 配置查詢 ECS 地區列表：

aliyun ecs describe-regions --profile prod

修改配置

使用 aliyun configure set 修改已有配置的參數值。只需指定要修改的參數，未指定的參數保持不變。

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

常用參數：

--region：預設地區
--language：輸出語言（zh / en）

詳細參數請參見各憑證類型文檔。

樣本：修改 default 配置的預設地區：

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

說明

執行修改後，該配置會自動成為當前啟用的配置。

刪除配置

運行以下命令刪除指定配置：

aliyun configure delete --profile <ProfileName>

樣本：刪除名為 dev 的配置：

aliyun configure delete --profile dev

重要

刪除操作不可恢複。刪除當前啟用配置後，配置列表中的第一個配置自動成為新的當前啟用配置。

刪除完成後，運行 aliyun configure list 命令確認該配置已從列表中移除。

常見問題

互動式配置時輸錯了怎麼辦？

使用 aliyun configure set 修改對應欄位即可，無需重新完整配置。樣本：

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

執行 CLI 命令時未使用當前啟用配置

CLI 按以下優先順序（從高到低）決定實際使用的配置，高優先順序會覆蓋低優先順序：

--profile 命令列參數：僅對當前命令生效，優先順序最高。
環境變數 ALIBABA_CLOUD_PROFILE：對當前終端會話中的所有命令生效。
當前啟用的預設配置：aliyun configure list 命令返回中帶有*的配置，持久生效。

如果命令結果與預期不符，請檢查是否設定了 --profile 參數或 ALIBABA_CLOUD_PROFILE 環境變數，它們會覆蓋當前啟用配置。運行 echo $ALIBABA_CLOUD_PROFILE 命令可查看環境變數是否已設定。

執行CLI命令時遇到報錯`load current configuration failed unknown profile default`

完整報錯資訊：

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

原因：

刪除了當前所有的憑證配置，導致阿里雲CLI無法正常工作。

解決方案：

手動刪除 config.json 檔案，並執行 aliyun configure 命令重新設定憑證，設定檔所在位置可參見憑證配置儲存位置。例如，在 Linux / macOS 上可執行以下命令刪除：

rm ~/.aliyun/config.json