# Ipa Stack Cognito

> Deploy a Cognito User Pool stack with OAuth 2.0 Hosted UI and OIDC endpoints.

- Skill: `aws-samples/ipa-stack-cognito` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aws-samples/ipa-stack-cognito`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/ipa-stack-cognito/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/ipa-stack-cognito

---


# ipa-stack-cognito

Deploy a Cognito User Pool with App Client, Custom Domain (Hosted UI), and Managed Login Branding. Provides authentication outputs for API Gateway authorizers, Lambda JWT validation, and frontend OIDC flows.

## Stack Identity

| Property | Value |
|----------|-------|
| Stack name | `{APP_NAMESPACE}-{APP_ENV}-cognito` |
| Template | `infra/cfn/cognito/cognito.yml` |
| Capabilities | none |
| Lifecycle | prepare (prerequisite stack) |
| Tier | cognito |

## Parameters

| Parameter | Type | Default | Validation | Error Message |
|-----------|------|---------|------------|---------------|
| Namespace | String | — | `/^[a-z][a-z0-9-]{0,11}$/` | "Invalid namespace — 1-12 chars, lowercase alphanumeric + hyphens, starts with letter" |
| Environment | String | — | `/^[a-z][a-z0-9-]{0,11}$/` | "Must be 1-12 chars, lowercase letters/digits/hyphens, starts with letter" |
| CallbackURL | String | `http://localhost:8080/authentication/callback` | `/^https?:\/\/.+$/` | "Must be a valid HTTP(S) URL" |
| CognitoDomainPrefix | String | — | `/^[a-z][a-z0-9-]{0,62}$/` | "Must be 1-63 lowercase chars, starts with letter, no reserved words (cognito, aws, amazon)" |

**CognitoDomainPrefix convention**: Set to `$(APP_NAMESPACE)-$(APP_ENV)-$(APP_ACCOUNT_HASH)` in `--parameter-overrides`. `APP_ACCOUNT_HASH` is a Make variable derived in the Makefile header via `$(shell echo -n "$(AWS_ACCOUNT_ID)" | shasum | cut -c1-8)`. This produces a globally-unique, account-safe domain prefix without exposing the AWS account ID.
| MinPasswordLength | Number | 8 | `8-99` | "Must be between 8 and 99" |
| DeletionProtection | String | INACTIVE | `ACTIVE \| INACTIVE` | "Must be ACTIVE or INACTIVE" |

All parameters are **Configuration** type — sourced from `.env` or defaults. No wirable parameters from other stacks.

## Outputs

| Output | Description | Export Convention | Used By |
|--------|-------------|------------------|---------|
| UserPoolId | ID of the Cognito User Pool | `{StackName}-UserPoolId` | Admin operations |
| UserPoolArn | ARN of the Cognito User Pool | `{StackName}-UserPoolArn` | ipa-stack-backend (JWT authorizer), ipa-stack-queue (JWT authorizer) |
| UserPoolClientId | ID of the App Client | `{StackName}-UserPoolClientId` | ipa-stack-backend (AuthAudience), ipa-stack-queue (AuthAudience) |
| IssuerUrl | OIDC Issuer base URL | `{StackName}-IssuerUrl` | ipa-stack-backend (AuthIssuer), ipa-stack-queue (AuthIssuer) |
| EndSessionEndpoint | Cognito logout base URL | `{StackName}-EndSessionEndpoint` | Frontend OIDC config |
| HostedUIURL | Full Cognito login URL | `{StackName}-HostedUIURL` | Runbook reference |
| CognitoDomain | Domain prefix value | `{StackName}-CognitoDomain` | Frontend OIDC authority |
| DiscoveryUrl | OIDC Discovery URL | `{StackName}-DiscoveryUrl` | JWT validation libraries |

## Security Summary

**Required IAM actions**: cognito-idp:CreateUserPool, UpdateUserPool, DeleteUserPool, DescribeUserPool, CreateUserPoolClient, UpdateUserPoolClient, DeleteUserPoolClient, CreateUserPoolDomain, DeleteUserPoolDomain, DescribeUserPoolDomain, SetUICustomization, CreateManagedLoginBranding, DeleteManagedLoginBranding — scoped to `arn:aws:cognito-idp:{Region}:{AccountId}:userpool/*`
**Security controls**: Advanced Security Mode ENFORCED, AdminCreateUserOnly, PreventUserExistenceErrors ENABLED, OAuth 2.0 Authorization Code Grant only
**Full advisory**: See [SECURITY.md](SECURITY.md)

## Terraform Module

| Property | Value |
|----------|-------|
| Module path | `infra/tf/cognito/` |
| State key | `{namespace}-{env}/cognito/terraform.tfstate` |
| Required version | `>= 1.5.0` |
| Providers | `hashicorp/aws >= 5.0` |

### Variables

| Variable | Type | Default | Maps to CFN |
|----------|------|---------|-------------|
| namespace | string | — | Namespace |
| environment | string | — | Environment |
| region | string | — | (implicit) |
| state_bucket | string | — | (TF infrastructure) |
| cognito_domain_prefix | string | — | CognitoDomainPrefix |
| callback_url | string | `http://localhost:8080/authentication/callback` | CallbackURL |

### Outputs

| Output | Maps to CFN |
|--------|-------------|
| user_pool_id | UserPoolId |
| user_pool_arn | UserPoolArn |
| user_pool_client_id | UserPoolClientId |
| issuer_url | IssuerUrl |
| end_session_endpoint | EndSessionEndpoint |
| cognito_domain | CognitoDomain |
| discovery_url | DiscoveryUrl |