aws-auth

AWS 身份验证（Amazon Cognito）

使用 Amazon Cognito 和 Amplify 客户端身份验证库进行应用级用户身份验证与授权。需要精确核实限制、配额和 API 的确切形式时，请查阅 AWS 官方文档；若与记忆中的信息冲突，以文档为准。

推荐： AWS MCP 服务可便捷访问此技能使用的 AWS API（Cognito 用户池／应用客户端／身份池设置、API Gateway 授权方）。如果无法使用，文中展示的 AWS CLI 命令可直接使用——此技能并不强制依赖 MCP。

不适用场景： Amplify Gen2 后端代码（defineAuth、amplify/auth.ts、npx ampx）；IAM 策略／角色／信任策略编写、STS 或 IAM Identity Center 控制台 SSO；API Gateway 路由／集成设置或 Lambda 函数实现（此技能只涵盖 Cognito/JWT 授权方配置以及 Cognito Lambda 触发器的用途）。

先选择用户池还是身份池

这两种服务并不相同，却经常被混淆。大多数应用需要用户池；只有在客户端必须直接调用 AWS 服务时，才添加身份池。

需求……	使用	原因
注册／登录、用户目录、颁发 JWT	用户池	它负责验证用户身份，也是一个 OIDC 身份提供方
让已登录的客户端使用 AWS 凭证直接调用 S3/DynamoDB 等服务	身份池	它通过 STS 将令牌换成临时 AWS 凭证
两者都需要（登录后从浏览器／应用访问 AWS 资源）	用户池 → 身份池	身份池信任用户池作为其身份提供方

如果你的应用只调用自己的后端／API，则不需要身份池——将用户池令牌发送给 API 即可。请参阅 identity-pools.md。

重要警告

update-user-pool-client 和 set-identity-pool-roles 会完全替换，而非部分更新：任何省略的字段都会重置为默认值——如果调用 update-user-pool-client 时只传入要更改的字段，就会在不发出提示的情况下清除 ExplicitAuthFlows、令牌有效期、EnableTokenRevocation、刷新令牌轮换以及读写属性；set-identity-pool-roles 也会替换整个角色及 RoleMappings 结构。务必先读取、修改，再写入：先调用 describe-user-pool-client（或 get-identity-pool-roles），然后重新发送所有现有字段及要做的更改。在 Agent 场景中，这种清除操作不会显现出来——调用会成功，直到用户遇到缺失的流程时才会出问题。参见 managed-login-oauth.md 和 identity-pools.md。

新应用不要使用隐式授权：隐式授权（response_type=token）已过时，会在 URL 片段中返回令牌。对于 SPA 和移动应用，请使用带 PKCE 的授权码授权（response_type=code + code_challenge）——面向公共客户端，无需客户端密钥。参见 managed-login-oauth.md。

高价值应用不要将刷新令牌存储在 localStorage 中：任何注入的脚本都能读取 localStorage（XSS）。Amplify 客户端库默认使用 localStorage；请改用 cookieStorage，缩短刷新令牌的有效期，并在应用客户端上启用刷新令牌轮换和令牌撤销。参见 tokens-and-sessions.md。

自定义访问令牌声明需要付费功能计划：在入门级计划（V1）上，预令牌生成触发器可以自定义 ID 令牌；但自定义访问令牌（V2/V3）需要付费功能计划——请查看 Cognito 功能计划文档，确认当前哪个计划包含此功能，因为计划名称及其包含的功能可能会变化。不要以为入门级计划支持访问令牌声明。参见 lambda-triggers.md。

应用客户端密钥 + SPA = 身份验证失效：公共客户端（浏览器/移动应用）不得设置客户端密钥。如果设置了密钥，令牌调用就必须发送 SECRET_HASH，否则会失败；而浏览器无法安全保护该密钥。只有机密客户端（服务端）才应生成密钥。

不要批量对 UNCONFIRMED 用户执行 admin-confirm-sign-up：用户卡在 UNCONFIRMED 状态时，优先使用 resend-confirmation-code，让每位用户通过 confirm-sign-up 重新验证并证明其拥有该邮箱（验证码可能已过期或被归入垃圾邮件）。admin-confirm-sign-up 会立即更改状态，但不会验证电子邮件——该属性仍处于未验证状态；如果邮箱用于密码重置或账户关联，这会很危险。仅对可信账户或迁移的账户使用此命令。参见 troubleshooting.md。

快速导航

您想要……	前往
创建用户池、注册/登录、MFA、密码策略、应用客户端	user-pools.md
添加托管式 UI / 托管登录、OAuth 流程、社交或 SAML 登录、回调 URL、自定义域名（us-east-1 中的 ACM）	managed-login-oauth.md
处理 ID/访问/刷新令牌、轮换、撤销、会话终止（全局登出与撤销及禁用）	tokens-and-sessions.md
为客户端提供临时 AWS 凭证、访客访问、角色映射	identity-pools.md
使用 Cognito 令牌保护 API Gateway API（并在后端强制执行自定义声明）	api-authorization.md
在 Application Load Balancer (ALB authenticate-cognito) 前添加 Cognito 登录	api-authorization.md
机器对机器（客户端凭证）身份验证、资源服务器、自定义作用域	managed-login-oauth.md
创建用户池组并将用户添加到组中（cognito:groups、Precedence）	user-pools.md
自定义声明、自定义身份验证质询流程、迁移用户、验证注册	lambda-triggers.md
添加 通行密钥 / WebAuthn 登录（USER_AUTH 流程、AllowedFirstAuthFactors、WebAuthn 注册）	passkeys.md
配置 威胁防护——阻止已泄露凭证、自适应身份验证（基于风险的 MFA）、将日志发送到 CloudWatch	threat-protection.md
遇到问题（重定向、令牌、MFA、CORS、社交登录）	troubleshooting.md

常见工作流

“为我的 React 应用添加注册和登录” → 创建用户池和一个公共应用客户端（无密钥），启用托管式 UI / 托管登录，并使用带 PKCE 的授权码授权，接入 Amplify 客户端库。请参阅 user-pools.md 和 managed-login-oauth.md。

“添加 Google / 社交登录” → 在用户池中注册社交 IdP，映射属性，并将提供商添加到应用客户端和托管式 UI。请参阅 managed-login-oauth.md。

“只有经过身份验证的用户才能调用我的 API” → HTTP API → JWT 授权方；REST API → Cognito 用户池授权方。请参阅 api-authorization.md。

“让浏览器在登录后上传到 S3” → 使用用户池进行登录，然后使用身份池提供受限范围的临时凭证。请参阅 identity-pools.md。

故障排查

错误/症状	可能原因	快速修复
登录后出现 redirect_mismatch / 重定向到错误的 URL	未注册回调 URL，或协议、尾部斜杠、大小写不一致	将准确的回调 URL（包括协议和路径）添加到应用客户端的 Allowed callback URLs 中
Token 调用失败，并提示“unable to verify secret hash”	在公共客户端（SPA/移动端）上设置了客户端密钥	重新创建不含密钥的应用客户端，或从机密客户端发送 SECRET_HASH
使用有效 Token 时，用户从 API Gateway 收到 401	Token 类型错误，或受众/颁发者不匹配	HTTP JWT 授权方：颁发者为 https://cognito-idp.{region}.amazonaws.com/{userPoolId}，受众 = 应用客户端 ID；发送授权方所需的 Token
调用托管 UI / Token 端点时出现 CORS 错误	浏览器跨域调用 /oauth2/token，或 API 缺少 CORS 配置	使用 PKCE 执行代码交换；不要从浏览器代理 Token 端点
社交登录用户提示“already exists” / 属性冲突	不同提供商使用相同邮箱会创建独立用户	启用属性映射和账户关联；不要将邮箱视为跨 IdP 唯一

完整表格见 troubleshooting.md。

安全注意事项

• 公共客户端（SPA/移动端）：不要设置客户端密钥，使用带 PKCE 的授权码授权，并请求最小权限范围。
• 启用 MFA（TOTP 或 SMS）、强密码策略，以及可用时的高级安全 / 威胁防护。
• 缩短访问 Token 的有效期；启用刷新 Token 轮换和 Token 撤销；优先使用 cookieStorage，而非 localStorage。
• 身份池：严格限制已认证 IAM 角色的权限；除非确有需要，否则禁用未认证（访客）访问。
• 每次受保护请求都要根据用户池 JWKS 验证 JWT（iss、aud/client_id、token_use、exp）。使用 aws-jwt-verify 等维护良好的库，而不是自行编写验证逻辑。
• 为应用网页设置安全标头：Content-Security-Policy（限制脚本来源以缓解窃取 Token 的 XSS）、Strict-Transport-Security（HSTS）、X-Frame-Options/frame-ancestors（防止登录页面遭受点击劫持），以及 X-Content-Type-Options: nosniff。
• 启用日志记录和监控：使用 CloudTrail 记录 Cognito API 事件（注册/登录/管理），启用用户池威胁防护（自适应身份验证和事件日志记录），针对身份验证失败/限流设置 CloudWatch 警报，并启用 API Gateway 访问日志以记录授权方的决策。
• 所有 Cognito 和 API 端点都只能使用 HTTPS/TLS；在 CloudWatch 日志组、用于 MFA/通知的 SNS 主题，以及由身份池支持的任何上传存储桶上，启用静态加密并使用客户管理的 KMS 密钥（同时限制密钥访问权限）。
• 如果使用 SNS 发送 MFA/通知，请为主题启用服务器端加密（KMS），并确保 SMS/电子邮件消息内容仅包含收件人所需的信息——不要包含超出消息需要范围的个人身份信息。
• 参考资料：Amazon Cognito 安全功能（用户池）、Amazon Cognito 安全性（顶层文档，包括身份池）和 IAM/STS 最佳实践。

本技能未涵盖内容时的查阅指南

如果需要了解本技能未涵盖的详细信息——例如确切的参数结构、当前限制和边缘行为——请查阅权威的 AWS 资料，而不要猜测。指引比内容更新得慢得多，因此即使本技能不再扩展，这份指南仍然有用。

• API 参考（确切参数、默认值、错误）： Cognito User Pools API 和 Cognito Identity API
• 开发者指南（概念、工作流）： Amazon Cognito Developer Guide
• 配额、速率限制、会话 Cookie 有效期： Cognito quotas
• 功能套餐 / 层级限制： Cognito feature plans
• 定价： Amazon Cognito pricing
• CLI 参考： aws cognito-idp 和 aws cognito-identity

本技能未涵盖的内容

• Amplify Gen2 后端（defineAuth、amplify/auth.ts、npx ampx sandbox）。
• IAM 策略 / 角色 / 信任策略编写、STS、IAM Identity Center 控制台 SSO。
• API Gateway 路由 / 集成设置和 Lambda 函数实现（本技能仅涵盖 Cognito/JWT 授权器配置，以及 Cognito Lambda 触发器的用途）。