AWS CLI 中 Cognito User Pools 的 change-password 命令详解：参数、模型与底层实现
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
本文以 AWS CLI 仓库中的官方示例文档change-password.rst为主体，围绕aws cognito-idp change-password命令展开：先完整继承原示例的命令用法，再结合仓库内 botocore 的 API 模型数据（service-2.json）逐一解析三个参数的必填性、取值约束与敏感标记，并说明该示例文档是如何被 CLI 的帮助系统注入到aws help输出中的，帮助读者既能直接复制命令完成"当前登录用户改密"操作，也能理解命令背后 API 模型与文档机制的实现细节。
命令示例：更改当前登录用户的密码
原始示例文档（change-password.rst）给出的核心内容只有一条命令，其作用是更改当前已登录用户的密码——注意这里强调"当前用户"，该操作由用户本人持有访问令牌发起，而非管理员操作：
aws cognito-idp change-password --previous-password OldPassword --proposed-password NewPassword --access-token ACCESS_TOKEN命令中的三个占位值含义如下：
OldPassword：用户当前的旧密码；NewPassword：用户在应用中被提示输入的新密码；ACCESS_TOKEN：Amazon Cognito 颁发给"要修改密码的那位用户"的有效访问令牌（access token）。
一个贴近实际使用的示例（在 Linux/macOS shell 中）：
aws cognito-idp change-password \ --previous-password 'OldPassword123!' \ --proposed-password 'NewPassword456!' \ --access-token 'eyJraWd...' \ --output json实际执行中建议为密码值加引号，避免特殊字符被 shell 解释；--output json便于以结构化方式确认调用结果。
API 模型视角：命令参数从哪里来
AWS CLI 并不是为每个服务硬编码参数，而是由 botocore 从内置的 API 模型文件中动态生成。对于 cognito-idp 服务，模型文件是 service-2.json（API 版本 2016-04-18）。ChangePassword操作在模型中的定义（见 service-2.json）包含以下关键信息：
| 模型属性 | 值 | 含义 |
|---|---|---|
| HTTP 方法与请求路径 | POST / | 请求统一 POST 到 cognito-idp 端点根路径 |
| 输入结构 | ChangePasswordRequest | 对应--previous-password/--proposed-password/--access-token三个 CLI 参数 |
| 输出结构 | ChangePasswordResponse | 空结构，无返回字段 |
| 认证方式 | authtype: none（noAuth） | 请求本身不走 IAM 签名，改用用户访问令牌鉴权 |
其中模型的documentation字段明确写道："Changes the password for the currently signed-in user. Authorize this action with a signed-in user's access token. It must include the scopeaws.cognito.signin.user.admin."——即访问令牌必须包含aws.cognito.signin.user.admin作用域。同时模型特别注明：该操作不评估 IAM 策略，不能使用 IAM 凭据发起请求，也不存在可授予的 IAM 权限，其授权模型完全依赖用户访问令牌。
请求参数详解（ChangePasswordRequest）
请求结构定义见 service-2.json，required数组声明为["ProposedPassword", "AccessToken"]，即：
| CLI 参数 | 模型成员 | 必填 | 说明 |
|---|---|---|---|
--previous-password | PreviousPassword | 否（条件性） | 用户当前密码。模型文档注明：如果用户没有密码、仅使用无密码认证方式（如社交登录）登录，则可以省略此参数 |
--proposed-password | ProposedPassword | 是 | 用户在新密码提示下输入的新密码 |
--access-token | AccessToken | 是 | Cognito 颁发给待改密用户的有效访问令牌 |
两个密码参数均引用PasswordType（见 service-2.json），其约束为：
- 类型为字符串，最长256字符；
- 正则约束
[\S]+，即密码不能包含空白字符； - 标记为
sensitive: true，属于敏感数据（CLI 在帮助文档和日志场景下会对此类字段做特殊处理）。
响应结构ChangePasswordResponse是一个不含任何成员的空结构：命令成功执行时通常没有任何 JSON 字段输出，退出码为 0；若返回了错误信息，则是模型中声明的异常之一（见下节）。
可能的错误：模型声明的 13 种异常
模型为ChangePassword显式声明了 13 种可能的异常（见 service-2.json），排障时可按此清单对照：
| 异常 | 典型触发场景 |
|---|---|
NotAuthorizedException | 访问令牌无效、过期，或用户状态不允许该操作 |
InvalidParameterException | 参数格式/取值不合法（如密码含空白字符） |
InvalidPasswordException | 新密码不符合用户池的密码策略 |
PasswordHistoryPolicyViolationException | 新密码命中密码历史策略（不能重复使用旧密码） |
PasswordResetRequiredException | 该用户处于"必须先重置密码"状态（如管理员创建用户后的强制首登改密），此时应走forgot-password或admin-reset-user-password流程而非直接改密 |
UserNotFoundException | 令牌对应的用户在池中不存在 |
UserNotConfirmedException | 用户注册尚未完成确认（邮箱/手机未验证） |
ResourceNotFoundException | 相关资源（如用户池）不存在 |
TooManyRequestsException | 请求频率过高被限流 |
LimitExceededException | 超出服务配额 |
OperationNotEnabledException | 该操作在用户池中未启用 |
InternalErrorException | 服务端内部错误，可重试 |
ForbiddenException | 禁止执行 |
需要特别区分的是PasswordResetRequiredException：当管理员通过admin-create-user创建用户（未指定初始密码）后，用户首次登录时 Cognito 会要求强制重置密码；此时直接调用change-password会失败，应先通过aws cognito-idp forgot-password完成重置，再进行常规改密。
与管理员改密操作的区分
change-password属于用户自助操作（API 前缀无admin-），其入口条件是"持有该用户自己的 access token"。仓库的同一示例目录下还有两个容易混淆的管理员操作文档：
- admin-set-user-password.rst：管理员直接为用户设定密码（使用 IAM 凭据 + 管理员权限，参数为
--user-pool-id/--username/--password，可选--permanent）； - admin-reset-user-password.rst：管理员触发用户密码重置，使用户进入"下次登录必须先改密"状态。
三者适用场景对比：
| 场景 | 命令 | 凭据要求 |
|---|---|---|
| 用户本人改密（已知旧密码） | change-password | 用户 access token（含aws.cognito.signin.user.adminscope） |
| 管理员替用户强制设密 | admin-set-user-password | IAM 凭据 + Cognito 管理员权限 |
| 管理员触发用户重置密码 | admin-reset-user-password | IAM 凭据 + Cognito 管理员权限 |
另外，若用户在自助流程中忘记密码（无法提供旧密码），应使用 forgot-password.rst 对应的forgot-password流程，而不是change-password。
示例文档如何进入 CLI 帮助输出
change-password.rst这类文件并非独立网页文档，而是被 AWS CLI 的帮助系统动态注入到aws help/aws cognito-idp change-password help输出中的"Examples"章节。其机制在 addexamples.py 中实现：
- 该定制模块将
add_examples函数注册到doc-examples.*.*文档事件上（由 awscli/customizations/init.py 完成注册）； - 事件触发时，函数按
examples/<服务名>/<操作名>.rst的命名规则拼接路径（见 addexamples.py），cognito-idp 的change-password操作正好命中 change-password.rst； - 若文件存在，则在帮助文本中先写入 "Examples" 二级标题和一条注记（提示需安装配置 AWS CLI、示例使用类 Unix 引用规则），随后将 .rst 文件内容逐行写入文档（见 addexamples.py）。
因此在仓库中直接阅读该 .rst 文件，与在终端执行aws cognito-idp change-password help看到 Examples 章节的内容是一致的；若想让帮助系统展示更多操作示例，也是按照同样的examples/<service>/<operation>.rst命名约定添加内容文件即可（此处仅说明机制，仓库为只读，不建议直接修改）。
使用前提与注意事项
- CLI 需已安装并完成凭据配置：虽然
change-password请求本身使用用户访问令牌鉴权（模型中标记为 noAuth），但 CLI 仍需要能定位 cognito-idp 端点，通常意味着已配置默认 region 或显式指定--region（若用户池部署在非默认区域，建议通过--endpoint-url指向具体端点）； - 访问令牌的获取：token 通常来自
initiate-auth/respond-to-auth-challenge等认证流程的响应，或经由 Cognito Identity Provider 端点（user pool endpoint，而非 IAM API 端点）颁发； - 密码约束：新密码须满足用户池配置的密码策略（长度、字符类别等），且不能与密码历史策略冲突，否则会收到
InvalidPasswordException或PasswordHistoryPolicyViolationException； - 密码不得含空白字符：由模型中
PasswordType的[\S]+正则约束决定，最长 256 字符； - 成功时输出为空：响应结构无字段，命令成功仅体现为无错误、退出码 0；
综合来看，该示例文档虽然只有一行命令，但结合 service-2.json 中ChangePassword操作的完整模型定义，可以确认其三个参数的必填性、敏感标记、HTTP 传输方式、令牌作用域要求以及完整的错误面——这正是 AWS CLI "数据驱动命令生成"设计哲学的典型缩影：仓库内一个 API 模型 JSON 文件，同时决定了命令参数、帮助文本、序列化行为与错误类型。
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
