# Cognito

> Builds, configures, and manages AWS Cognito user pools, identity pools, authentication flows, and integrations with other AWS services.

- Skill: `luokai0/cognito` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add luokai0/cognito`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luokai0/cognito/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra, Security, Cloud Platforms, Secure Coding
- Tags: Authentication, Aws Cognito, Identity Pool, Lambda Triggers, Mfa, Oauth, Saml, User Pool
- Author: luokai0 (https://skillmd.com/u/luokai0)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/luokai0/cognito

---


# AWS Cognito Skill

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?

1. **New Cognito setup from scratch** → Read `references/setup-guide.md`, then follow the setup workflow
2. **CDK / CloudFormation / Terraform IaC** → Read `references/iac-patterns.md` for production-ready templates
3. **Authentication flow implementation** → Read `references/auth-flows.md` for SDK code and flow selection
4. **Debugging / troubleshooting** → Read `references/troubleshooting.md` for common issues and fixes
5. **Lambda triggers** → Read `references/lambda-triggers.md` for trigger patterns
6. **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.