配置阿里云CLI OAuth 凭证

更新时间:
复制 MD 格式

通过浏览器完成一次登录授权,即可让阿里云 CLI 获得调用云服务 API 的临时访问凭证。CLI 自动管理令牌的刷新和续期,无需在本地存储或手动轮换长期访问密钥(AccessKey),是本地开发环境的推荐认证方式。本文介绍 OAuth 凭证的前置准备、配置授权流程、凭证验证,以及令牌的生命周期与自动刷新机制。

前提条件

环境要求

  • 阿里云 CLI 版本 ≥ 3.3.0。运行 aliyun version 命令查看当前版本。版本低于 3.3.0 时,请参考安装/更新 CLI升级后再使用 OAuth 凭证。

  • 需要拥有能够登录控制台的账号,可以是:阿里云账号(主账号)、RAM 用户或通过 SSO 登录的企业用户。如果使用 RAM 用户,需确认已启用控制台登录,详见启用控制台登录。

  • 本地浏览器登录方式需要在运行阿里云 CLI 的环境中打开浏览器。阿里云 CLI 3.5.2 及以上版本也支持手动登录:运行配置命令时显式添加 --no-browser,即可在电脑或手机的浏览器中完成授权,并将完整回调 URL 粘回 CLI。纯终端环境可使用此方式,无需端口转发。

安装阿里云CLI应用并分配身份

首次使用 OAuth 前,需由 RAM 管理员完成以下操作。完成后,后续新增用户只需执行步骤 2 即可。

  1. 安装 CLI 应用(一次性):登录 RAM 控制台,在左侧导航栏选择集成管理 > OAuth 应用(公测)。切换到第三方应用页签。如果列表中没有 official-cli 应用,单击安装官方应用,选择官方 CLI 完成安装。

  2. 分配身份:进入 official-cli 应用详情页,切换到允许访问的身份页签。单击添加用户或角色将需要使用阿里云CLI 的 RAM 用户或角色添加到授权列表。

    9A6ADEC6-B635-4E63-B61C-87CB05122249

完整操作步骤,请参见步骤一:管理员创建CLI应用、步骤二:管理员分配身份。

配置凭证

重要

OAuth 凭证必须通过交互式命令 aliyun configure --mode OAuth 完成登录与授权。默认使用浏览器登录方式;添加 --no-browser 使用手动登录方式。aliyun configure set 命令仅写入参数,不会触发登录授权。

  1. 运行以下命令开始配置。将 <ProfileName> 替换为自定义的配置名称(如 OAuthProfile):

    aliyun configure --mode OAuth --profile <ProfileName>
  2. 选择登录站点OAuth Site Type:

    aliyun configure --profile OAuthProfile --mode OAuth
    Configuring profile 'OAuthProfile' in 'OAuth' authenticate mode...
    OAuth Site Type (CN: 0 or INTL: 1, default: CN): 
    • 输入0或CN:设置登录站点为阿里云中国站。

    • 输入1或INTL:设置登录站点为阿里云国际站。

    • 直接回车:默认选择中国站(CN)。

  3. 用户登录。在自动弹出的浏览器窗口中,使用您的RAM用户身份登录。如果浏览器窗口未弹出,可以根据CLI的提示信息,手动复制登录URL(SignIn url)至浏览器中,完成登录和授权操作。

    Please open the following URL in your browser to authorize:
    https://signin.aliyun.com/oauth2/v1/auth?...
  4. 执行用户授权操作。在浏览器打开的用户授权页面,单击授权。授权成功后,浏览器页面显示Authorization successful. You can close this window.,此时可关闭浏览器窗口。

  5. 设置默认地域及语言,如:

    Default Region Id []: cn-shanghai
    Default Language [zh|en] en: en

    具体地域请参见地域和可用区。部分云产品不支持跨地域访问,建议您优先将默认地域设置为已购资源所在地域。

  6. 终端显示 Configure Done 及欢迎信息,表示配置成功。

说明

配置成功后,该配置自动成为当前激活的配置。如需切换到其他配置,运行 aliyun configure switch --profile <ProfileName> 命令。

手动登录(跨设备)

阿里云 CLI 3.5.2 及以上版本支持手动登录。适用于运行 CLI 的环境无法打开浏览器、需要在其他电脑或手机完成登录的场景。此方式必须显式添加 --no-browser。中国站和国际站均支持。

  1. 在运行 CLI 的终端执行以下命令。oauth-profile 为本示例的自定义配置名称,可替换为您的配置名称。

    aliyun configure --mode OAuth --profile oauth-profile --no-browser

    新建 profile 时,终端先提示选择登录站点:

    Configuring profile 'oauth-profile' in 'OAuth' authenticate mode...
    OAuth Site Type (CN: 0 or INTL: 1, default: CN): 

    输入 0 或 CN 选择中国站,输入 1 或 INTL 选择国际站,直接回车默认选择 CN。中国站授权域名为 https://signin.aliyun.com,国际站为 https://signin.alibabacloud.com。

  2. 复制终端本次生成的授权链接,在电脑或手机浏览器中打开,登录并完成授权。手动模式显示以下英文提示。示例授权 URL 的 ... 表示动态值省略,实际登录必须使用当前终端生成的完整链接,不能直接使用文档示例。

  3. 授权后浏览器会跳转到以 http://127.0.0.1:12345/cli/callback 开头的本地地址。手动模式没有监听此端口,页面打不开或提示连接失败是正常现象,不影响地址栏中回调 URL 的有效性。

  4. 从浏览器地址栏复制完整的回调 URL,包括 code 和 state 参数,粘贴到当前 CLI 会话的 Callback URL (Ctrl+C to cancel): 提示后,按回车。不是输入设备码、短码或校验码,也不能只粘贴 code 值。回调 URL 的协议、主机、端口、路径必须为 http://127.0.0.1:12345/cli/callback,state 必须与本次登录匹配,code 必须非空;不要粘贴其他登录会话的地址或添加 URL fragment。按 Ctrl+C 可取消。

    若粘贴的回调地址不符合要求,CLI 显示以下提示,请重新复制本次登录的完整回调 URL:

    invalid OAuth callback address. Please paste the complete callback URL for this login.
  5. 成功后,终端显示:

    OAuth configuration completed. The temporary Access Key Id and Access Key Secret have been set in the profile.

    按终端提示继续设置默认地域及语言,完成 profile 配置。

凭证的刷新

OAuth 凭证由以下三层令牌组成,CLI 自动管理令牌续期,日常使用无需手动干预:

  • 临时安全凭证(STS Token)

  • OAuth 访问令牌(Access Token)

  • OAuth 刷新令牌(Refresh Token)

说明

令牌每次成功续期后自动轮换,旧令牌同时作废,配置文件(~/.aliyun/config.json)自动更新。

删除凭证

运行以下命令删除指定的 OAuth 配置:

aliyun configure delete --profile <ProfileName>

删除后:

  • 该 profile 从 ~/.aliyun/config.json 中移除,本地存储的 OAuth 令牌和STS Token一并清除。

  • 不影响 RAM 控制台中 OAuth 应用的授权配置,无需管理员重新操作。

常见问题

授权时浏览器未自动弹出怎么办?

未添加 --no-browser 时,使用默认浏览器登录方式。CLI 会在终端打印登录 URL,手动复制到浏览器打开即可。若页面无法加载,请检查:

  • 本地端口 12345–12349 是否被占用(CLI 需要监听其中一个端口接收授权回调)

  • 与阿里云登录端点 signin.aliyun.com(中国站)或 signin.alibabacloud.com(国际站)的网络连通状况

如果 CLI 运行环境没有浏览器,请使用上文手动登录方式;该方式无需监听本地端口或端口转发,授权后的回调页面连接失败属正常现象。

用户授权时报错调用未被授权/ You are not allowed to do this action.

管理员未在用户所在的阿里云账号下安装CLI应用,请参考安装阿里云CLI应用并分配身份中的步骤进行安装并将用户添加到official-cli OAuth 应用的授权列表。

已有 AK 配置,想切换到 OAuth,需要先删除 AK 配置吗?

不需要。创建一个新的 OAuth profile 后,原有配置仍然保留,可以使用命令aliyun configure switch --profile <profile-name>命令进行切换。

CLI的OAuth认证方式是否支持RAM角色登录?

支持。您可以使用以下两种方式:

  • 在浏览器中使用角色SSO的方式从身份提供商(IdP)侧完成控制台登录。需要配置了角色SSO才可以实现。

  • 在使用RAM用户登录控制台后切换身份到对应RAM角色。

以上操作需要在配置OAuth凭证前操作,以便在配置OAuth凭证弹出浏览器弹窗时自动识别当前登录身份为RAM角色。