AWS CLI 获取 CodeArtifact 授权令牌:get-authorization-token 命令实战指南
AWS CLI 获取 CodeArtifact 授权令牌:get-authorization-token 命令实战指南
本指南以 AWS CLI 的 codeartifact get-authorization-token 命令为核心,讲解如何为 CodeArtifact 域(Domain)生成临时授权令牌,并将其用于 npm、pip、twine、nuget 等包管理工具的身份认证。读完本文,你将掌握该命令的完整参数、返回值、有效期控制方式、与 codeartifact login 命令的内部调用关系,以及令牌落盘配置的安全最佳实践,能够直接在自己的构建与 CI/CD 流程中落地使用。
背景:CodeArtifact 为什么需要授权令牌
AWS CodeArtifact 是托管的软件包制品仓库服务,支持 npm、PyPI、Maven、NuGet、Swift 等多种包格式。包管理工具在拉取或发布制品时,需要向 CodeArtifact 仓库发起经过身份认证的 HTTP 请求,而认证凭据就是授权令牌(authorization token)。
授权令牌并非长期密钥,而是由 CodeArtifact 服务动态签发、有明确过期时间的临时凭据,有效期最长不超过 12 小时。这与长期访问密钥相比更安全:即使令牌泄露,其危害范围和时间窗口都受到严格限制。
本文对应的示例文档位于 get-authorization-token.rst,它是 AWS CLI 内置帮助系统中该命令的官方示例;命令的底层 API 定义(参数、返回结构、错误类型)则记录在 service-2.json 中,下文将逐一展开。
命令基础用法
获取授权令牌的核心命令如下(完整继承自示例文档):
aws codeartifact get-authorization-token \
--domain test-domain \
--query authorizationToken \
--output text
各参数含义:
--domain test-domain:指定生成令牌的 CodeArtifact 域名称,这是必填参数;--query authorizationToken:仅从返回结果中提取authorizationToken字段;--output text:以纯文本格式输出,便于直接捕获或写入环境变量。
输出效果:命令会返回授权令牌字符串。示例文档明确指出,在实际使用中应将输出保存到环境变量中,供后续包管理工具调用。
参数详解与取值范围
根据 service-2.json 中 GetAuthorizationTokenRequest 结构体的定义,get-authorization-token 支持以下三个参数:
| 参数 | 是否必填 | 说明 | 约束 |
|---|---|---|---|
--domain |
是 | 生成令牌所作用的域名称 | 字符串,位于请求的 query string |
--domain-owner |
否 | 拥有该域的 AWS 账户 12 位账号 ID(不含连字符和空格) | 仅当域名所有者与当前凭证账户不同时需要指定 |
--duration-seconds |
否 | 令牌的有效时长(秒) | 合法值为 0,或 900(15 分钟)到 43200(12 小时)之间的任意整数 |
其中 --duration-seconds 的行为值得特别注意,其取值语义在 API 定义中有明确说明:
- 取值
0:令牌过期时间与当前调用方角色临时凭证的过期时间保持一致(即跟随 STS 临时凭证的生命周期); - 取值在
900 ~ 43200之间:令牌在指定秒数后过期; - 未指定该参数时:令牌默认有效期为 12 小时。
从 service-2.json 的 API 文档还可以看到两个与有效期相关的重要事实:
- 通过
get-authorization-token可以自定义有效期(最多 12 小时); - 如果是在 AssumeRole 会话中调用该 API,令牌的生命周期与角色的最大会话时长相互独立——例如即使角色会话只有 15 分钟,生成的 CodeArtifact 令牌仍可拥有完整的授权有效期。
跨账户域访问
当目标域属于另一个 AWS 账户时,必须指定 --domain-owner:
aws codeartifact get-authorization-token \
--domain shared-domain \
--domain-owner 123456789012 \
--query authorizationToken \
--output text
自定义令牌有效期
aws codeartifact get-authorization-token \
--domain test-domain \
--duration-seconds 3600 \
--query authorizationToken \
--output text
上例生成有效期为 1 小时的令牌。
返回结果与输出解析
根据 GetAuthorizationTokenResult(见 service-2.json),该命令返回两个字段:
| 字段 | 类型 | 说明 |
|---|---|---|
authorizationToken |
String | 返回的认证令牌本体 |
expiration |
Timestamp | 令牌过期的日期与时间戳 |
完整查看两个字段,可以不指定 --query,直接以 JSON 输出:
aws codeartifact get-authorization-token --domain test-domain
输出形如:
{
"authorizationToken": "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1Qi...",
"expiration": "2026-09-15T14:44:00Z"
}
由于返回结果整体被标记为敏感数据("sensitive": true),生产环境中请避免将原始 JSON 输出打印到日志。推荐的做法如示例文档所示,用 --query 精确提取令牌字段。
保存到环境变量
将令牌存入环境变量是示例文档强调的标准用法,在 bash 中:
export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
--domain test-domain \
--query authorizationToken \
--output text)
Windows PowerShell 中对应:
$env:CODEARTIFACT_AUTH_TOKEN = aws codeartifact get-authorization-token --domain test-domain --query authorizationToken --output text
之后即可把 $CODEARTIFACT_AUTH_TOKEN 传给各类包管理工具完成认证。
用令牌配置包管理工具
获得令牌后,可以将其喂给不同的包管理客户端。以下结合本仓库 login.py 中各工具适配器类的实现,展示几种典型场景的等价手动配置方式。
配置 pip(Python)
从 PipLogin.PIP_INDEX_URL_FMT = '{scheme}://aws:{auth_token}@{netloc}{path}simple/'(login.py)可以看到,pip 的认证方式是把用户名 aws 和令牌直接拼进 index-url:
aws codeartifact get-repository-endpoint --domain test-domain --repository my-repo --format pypi
拿到仓库端点后,结合令牌配置 pip:
pip config set global.index-url "https://aws:${CODEARTIFACT_AUTH_TOKEN}@my-domain-123456789012.d.codeartifact.us-west-2.amazonaws.com/pypi/my-repo/simple/"
配置 npm(Node.js)
从 NpmLogin 的实现(login.py)可以看到 npm 需要三类配置:registry 地址、always-auth 开关、以及写入 .npmrc 的 _authToken:
# 1. 配置 registry
npm config set registry "https://my-domain-123456789012.d.codeartifact.us-west-2.amazonaws.com/npm/my-repo/"
# 2. 将令牌写入 ~/.npmrc
echo "//my-domain-123456789012.d.codeartifact.us-west-2.amazonaws.com/npm/my-repo/:_authToken=${CODEARTIFACT_AUTH_TOKEN}" >> ~/.npmrc
源码中还体现了两个细节:npm 会额外设置 always-auth=true 强制对仓库请求携带认证信息;写 .npmrc 时使用了权限为 0600 的临时文件并通过 os.replace 原子替换(见 login.py),避免明文令牌文件被他人读取,这一安全习惯值得手动配置时参考。
配置 twine(PyPI 发布)
TwineLogin.DEFAULT_PYPI_RC_FMT(login.py)展示了写入 ~/.pypirc 的格式:
[distutils]
index-servers=
pypi
codeartifact
[codeartifact]
repository: https://my-domain-123456789012.d.codeartifact.us-west-2.amazonaws.com/pypi/my-repo/
username: aws
password: <你的授权令牌>
发布制品时执行 twine upload --repository codeartifact dist/* 即可。
与 login 命令的关系:一条隐藏的调用链
get-authorization-token 并不只是独立命令,它还是 CodeArtifact 的 login 子命令的内部基石。从 login.py 的 CodeArtifactLogin._run_main 调用链可以清晰看到:
_get_authorization_token()内部调用codeartifact_client.get_authorization_token(**kwargs),即底层就是get-authorization-token对应的 API;- 随后
_get_repository_endpoint()调用get_repository_endpoint获取仓库端点; - 根据
--tool参数(swift/nuget/dotnet/npm/pip/twine)选择对应的登录适配器类,自动把令牌写入.npmrc、NuGet.Config、.pypirc、.netrc或执行对应客户端命令; - 最后通过
login()输出“Login expires in … at …”的成功信息,其到期时间正是由get_authorization_token返回的expiration字段换算而来(见_write_success_message,login.py)。
因此,get-authorization-token 可以看作 login 命令的“手动模式”:当你想完全掌控令牌的获取与注入方式(例如在容器或 CI 中不想让 CLI 改写配置文件)时,就使用本文的底层命令;当希望 CLI 代劳全部配置时,则使用 codeartifact login:
aws codeartifact login --tool pip --domain test-domain --repository my-repo
权限要求与错误处理
根据 service-2.json 中 GetAuthorizationToken 的定义,调用需要同时具备两类 IAM 权限:
codeartifact:GetAuthorizationToken:允许对指定域生成令牌;sts:GetServiceBearerToken:允许 CodeArtifact 服务签发 service bearer token。
可抛出的异常包括:AccessDeniedException(缺少权限)、ResourceNotFoundException(域不存在)、ValidationException(参数不合法,如 duration 超出范围)、ThrottlingException(请求被限流)、InternalServerException(服务端错误)。排查问题时可按此顺序检查:权限策略是否齐全 → 域名与账号 ID 是否正确 → 参数取值是否在合法区间。
安全实践小结
- 令牌是敏感数据:API 响应在模型层即被标记为敏感,输出时尽量用
--query提取字段,避免完整 JSON 进入日志; - 控制有效期:在安全要求高的场景使用
--duration-seconds缩短令牌寿命(最低 15 分钟),并通过定时任务或 CI 步骤周期性刷新; - 环境变量传递:优先使用环境变量而非把令牌硬编码进配置文件、脚本或仓库;
- 文件权限:需要把令牌写入
.npmrc、.pypirc等文件时,参考本仓库源码的做法,将文件权限收紧为0600,防止同机其他用户读取; - 及时清理:令牌最长 12 小时过期,若需撤销访问,应回收底层 IAM 凭证或调整域资源策略,而不是仅依赖令牌过期。
进一步探索
- 示例文档: get-authorization-token.rst、login.rst
- 底层 API 模型:service-2.json
- 各包管理工具登录适配器实现:login.py
- 域管理相关命令示例: create-domain.rst、list-domains.rst
- 仓库端点获取: get-repository-endpoint.rst