AWS Cognito 技能

该技能可帮助您构建、配置、调试和管理 AWS Cognito 资源——包括用户池（User Pools）、身份池（Identity Pools）、应用客户端（App Clients）、Lambda 触发器、联合身份认证（Federation），以及与其他 AWS 服务的集成。

快速决策：用户需要什么？

1. 从零开始新建 Cognito 配置 → 阅读 references/setup-guide.md，然后按设置工作流操作
2. 使用 CDK / CloudFormation / Terraform 进行基础设施即代码（IaC）管理 → 阅读 references/iac-patterns.md 获取可用于生产环境的模板
3. 实现认证流程（Authentication Flow） → 阅读 references/auth-flows.md 获取 SDK 示例代码及流程选型建议
4. 调试与排障 → 阅读 references/troubleshooting.md 了解常见问题及其修复方法
5. Lambda 触发器 → 阅读 references/lambda-triggers.md 了解触发器模式
6. 安全加固 → 阅读 references/security.md 了解最佳实践

在生成任何代码或配置前，请务必先阅读相关参考文档。多个文件可能同时适用——例如，新建一个基于 CDK 的配置时，应同时参考 setup-guide.md 和 iac-patterns.md。

核心概念（始终牢记）

用户池 vs 身份池

这是 Cognito 的两个主要组件，用途各不相同：

• 用户池（User Pool）：作为用户目录及 OIDC 身份提供商，负责处理注册、登录、MFA、签发令牌（ID Token、Access Token、Refresh Token），以及与外部身份提供商（IdP）的联合认证。可理解为“这个用户是谁？”
• 身份池（Identity Pool，即 Federated Identities）：将来自用户池、社交登录、SAML 或 OIDC 提供商的令牌，交换为临时 AWS 凭据（通过 STS）。可理解为“该用户可访问哪些 AWS 资源？”

典型架构会同时使用两者：用户池完成用户身份认证并签发令牌 → 身份池将这些令牌交换为 AWS 凭据 → 用户据此访问 S3、DynamoDB 等资源。

功能计划（Feature Plans，定价层级）

截至 2024 年底，Cognito 已采用功能计划（Feature Plans）替代旧版“高级安全”开关：

• Lite：低成本、基础认证功能，适用于 MAU（月活跃用户）较少的简单应用。
• Essentials（新创建用户池的默认选项）：包含所有最新认证功能，如 Access Token 自定义、托管登录（Managed Login）等。
• Plus：包含 Essentials 全部功能，并额外提供威胁防护能力（自适应认证、凭证泄露检测）。

务必向用户确认所需的功能计划；若未明确指定，新配置默认采用 Essentials。

令牌类型

• ID Token：包含用户身份声明（如 email、name、groups、自定义属性），用于后端的身份核验。
• Access Token：包含权限范围（scopes）与已授权操作，用于 API 授权（例如 API Gateway 中的 Cognito Authorizer）。
• Refresh Token：长期有效的令牌，用于在无需重新认证的前提下获取新的 ID Token / Access Token，默认有效期为 30 天。

构建 Cognito 解决方案的工作流

步骤 1：明确需求

在编写任何代码前，请先确认以下事项：

• 认证方式：用户名/密码？仅邮箱？仅手机号？社交登录（Google、Apple、Facebook）？企业级 SAML/OIDC？
• MFA：是否强制启用？是否可选？是否禁用？验证方式为 SMS、TOTP 认证器 App，还是邮箱？
• 自助注册：是否允许用户自助注册？还是仅支持管理员创建用户？
• 令牌用途：仅前端使用（SPA/移动端）？用于后端 API 授权？还是直接访问 AWS 资源？
• IaC 偏好：CDK（TypeScript/Python）、CloudFormation、Terraform，还是控制台/CLI？
• 前端框架：React/Amplify、Next.js、Vue、移动端（iOS/Android），还是自定义实现？

步骤 2：设计架构

根据需求确定以下设计要点：

• 用户池配置（登录别名、用户属性、密码策略、MFA 设置等）
• 应用客户端（App Client）类型 —— 公开型（无密钥，适用于 SPA/移动端） vs 机密型（含密钥，适用于服务端）
• OAuth 流程 —— 授权码模式（Authorization Code，公开客户端需配合 PKCE）、隐式模式（Implicit，已过时，应避免）、客户端凭据模式（Client Credentials，适用于 M2M 场景）
• 是否需要身份池（仅当用户需直接访问 AWS 资源时才需要）
• 所需的 Lambda 触发器（如 pre-sign-up、post-confirmation、pre-token-generation、custom auth 等）
• 域名 —— 使用 Cognito 托管的前缀域名，还是自定义域名？

步骤 3：实施

阅读对应参考文档并生成代码。请始终遵循以下原则：

• 使用最新版 CDK v2 构建模块（aws-cdk-lib/aws-cognito），切勿使用 CDK v1
• SDK 代码使用 AWS SDK v3（@aws-sdk/client-cognito-identity-provider），切勿使用 v2
• 前端优先采用 Amplify v6（aws-amplify）模式
• 包含完善的错误处理逻辑与令牌刷新机制
• 生产环境中，用户池资源需设置 RemovalPolicy.RETAIN（防止数据丢失）
• 切勿硬编码密钥 —— 应使用环境变量或 AWS Secrets Manager

步骤 4：安全审查

在宣布完成前，请依据 references/security.md 进行核验：

• 生产环境至少启用可选 MFA
• 密码策略符合要求（如最少 8 位字符、满足复杂度规则）
• 令牌有效期设置合理
• 面向公网的认证端点应考虑部署 WAF
• 身份池关联的 IAM 角色须遵循最小权限原则
• 机密型客户端（confidential clients）必须使用客户端密钥（client secret）
• 回调 URL 必须仅支持 HTTPS

常用模式速查

Cognito + API Gateway

在 API Gateway 上配置 Cognito 用户池授权方（Cognito User Pool Authorizer），Access Token 将被自动校验；Token 中的权限范围（scopes）决定用户可访问的 API 方法。

Cognito + AppSync

在 GraphQL API 上配置 AMAZON_COGNITO_USER_POOLS 授权类型，并在 Schema 中使用 @auth 指令实现细粒度访问控制。

Cognito + S3（通过 Identity Pool）

用户池 → 身份池 → 绑定具备 S3 权限的 IAM 角色，且权限范围限制为 ${cognito-identity.amazonaws.com:sub}/*，以实现按用户隔离的存储路径。

Cognito + Lambda（自定义认证）

采用 CUSTOM_AUTH 流程，配合 Define Auth Challenge、Create Auth Challenge 和 Verify Auth Challenge 触发器，实现无密码（Magic Link、OTP）或多步骤认证。

机器对机器（M2M）

使用 Client Credentials 授权模式，配合资源服务器（Resource Server）与自定义 scopes，实现应用到应用的认证（无需用户交互）。

重要提醒

• 用户池创建时标记为“必需”的属性，在创建后无法修改，请谨慎规划属性结构。
• 自定义属性名称必须以 custom: 为前缀（例如 custom:company）。
• sub 属性是唯一且不可变的用户标识符，应作为主键使用，而非 email 或 username。
• 邮箱/手机号验证与登录别名（sign-in aliases）是两个独立配置项；若将其设为登录别名，请同步启用自动验证（auto-verify）。
• Cognito 存在服务配额限制（例如 API 请求速率限制）。对于高并发应用，请提前申请提升配额。
• Lambda 触发器为同步执行，超时时间为 5 秒，请确保逻辑高效简洁。