This skill helps you build, configure, debug, and manage AWS Cognito resources — user pools, identity pools, app clients, Lambda triggers, federation, and integrations with other AWS services.

Quick Decision: What Does the User Need?

• New Cognito setup from scratch → Read references/setup-guide.md, then follow the setup workflow
• CDK / CloudFormation / Terraform IaC → Read references/iac-patterns.md for production-ready templates
• Authentication flow implementation → Read references/auth-flows.md for SDK code and flow selection
• Debugging / troubleshooting → Read references/troubleshooting.md for common issues and fixes
• Lambda triggers → Read references/lambda-triggers.md for trigger patterns
• Security hardening → Read references/security.md for best practices

Read the relevant reference file(s) before generating any code or configuration. Multiple files may apply — for example, a new CDK setup would benefit from both setup-guide.md and iac-patterns.md.

Core Concepts (Always Keep in Mind)

User Pools vs Identity Pools

These are the two main Cognito components and they serve different purposes:

• User Pool: A user directory and OIDC identity provider. Handles sign-up, sign-in, MFA, token issuance (ID token, access token, refresh token), and federation with external IdPs. Think of it as "who is this user?"
• Identity Pool (Federated Identities): Exchanges tokens (from a user pool, social provider, SAML, or OIDC) for temporary AWS credentials (STS). Think of it as "what AWS resources can this user access?"

A common architecture uses both: User Pool authenticates the user and issues tokens → Identity Pool exchanges those tokens for AWS credentials → User accesses S3, DynamoDB, etc.

Feature Plans (Pricing Tiers)

As of late 2024, Cognito uses feature plans instead of the old "advanced security" toggle:

• Lite: Low-cost, basic auth features. Good for simple apps with fewer MAUs.
• Essentials (default for new pools): All latest auth features including access-token customization and managed login.
• Plus: Everything in Essentials plus threat protection (adaptive auth, compromised credential detection).

Always ask the user which plan they need, or default to Essentials for new setups.

Token Types

• ID Token: Contains user identity claims (email, name, groups, custom attributes). Use for identity verification on your backend.
• Access Token: Contains scopes and authorized actions. Use for API authorization (e.g., API Gateway Cognito Authorizer).
• Refresh Token: Long-lived token to obtain new ID/access tokens without re-authentication. Default validity is 30 days.

Workflow: Building a Cognito Solution

Step 1: Clarify Requirements

Before writing any code, determine:

• Auth methods: Username/password? Email-only? Phone? Social login (Google, Apple, Facebook)? Enterprise SAML/OIDC?
• MFA: Required, optional, or off? SMS, TOTP authenticator app, or email?
• Self-service sign-up: Enabled or admin-only user creation?
• Token usage: Frontend-only (SPA/mobile)? Backend API authorization? Direct AWS resource access?
• IaC preference: CDK (TypeScript/Python), CloudFormation, Terraform, or console/CLI?
• Frontend framework: React/Amplify, Next.js, Vue, mobile (iOS/Android), or custom?

Step 2: Design the Architecture

Based on requirements, determine:

• User Pool configuration (sign-in aliases, attributes, password policy, MFA)
• App client(s) — public (no secret, for SPAs/mobile) vs confidential (with secret, for server-side)
• OAuth flows — Authorization Code (with PKCE for public clients), Implicit (legacy, avoid), Client Credentials (M2M)
• Whether an Identity Pool is needed (only if users need direct AWS resource access)
• Lambda triggers needed (pre-sign-up, post-confirmation, pre-token-generation, custom auth, etc.)
• Domain — Cognito-hosted prefix domain or custom domain

Step 3: Implement

Read the appropriate reference files and generate code. Always:

• Use the latest CDK v2 constructs (aws-cdk-lib/aws-cognito) — never CDK v1
• For SDK code, use AWS SDK v3 (@aws-sdk/client-cognito-identity-provider) — never v2
• For frontend, prefer Amplify v6 (aws-amplify) patterns
• Include proper error handling and token refresh logic
• Set RemovalPolicy.RETAIN on user pools in production (data loss prevention)
• Never hardcode secrets — use environment variables or AWS Secrets Manager

Step 4: Security Review

Before declaring done, verify against references/security.md:

• MFA is enabled (at least optional) for production
• Password policy meets requirements (minimum 8 chars, complexity rules)
• Token validity periods are reasonable
• WAF is considered for public-facing auth endpoints
• Least-privilege IAM for any Identity Pool roles
• Client secrets are used for confidential clients
• HTTPS-only callback URLs

Common Patterns Quick Reference

Cognito + API Gateway

Use a Cognito User Pool Authorizer on API Gateway. The access token is validated automatically. Scopes in the token control which API methods are accessible.

Cognito + AppSync

Configure AMAZON_COGNITO_USER_POOLS authorization on your GraphQL API. Use @auth directives in your schema for fine-grained access control.

Cognito + S3 (via Identity Pool)

User Pool → Identity Pool → IAM role with S3 permissions scoped to ${cognito-identity.amazonaws.com:sub}/* for per-user folders.

Cognito + Lambda (Custom Auth)

Use CUSTOM_AUTH flow with Define, Create, and Verify Auth Challenge triggers for passwordless (magic link, OTP) or multi-step authentication.

Machine-to-Machine (M2M)

Use Client Credentials grant with a resource server and custom scopes. No user interaction — one app authenticating to another.

Important Reminders

• User pool attributes marked as required at creation CANNOT be changed later. Plan attributes carefully.
• Custom attributes are always prefixed with custom: (e.g., custom:company).
• The sub attribute is the unique, immutable user identifier. Use it as your primary key, not email or username.
• Email/phone verification is separate from sign-in aliases. Auto-verify what you use for sign-in.
• Cognito has service quotas (e.g., API request rate limits). For high-volume apps, request quota increases proactively.
• Lambda triggers execute synchronously and have a 5-second timeout. Keep them fast.