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
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 |
1---2name: ipa-stack-cognito3description: Deploy a Cognito User Pool stack with OAuth 2.0 Hosted UI and OIDC endpoints.4---56# ipa-stack-cognito78Deploy 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.910## Stack Identity1112| Property | Value |13|----------|-------|14| Stack name | `{APP_NAMESPACE}-{APP_ENV}-cognito` |15| Template | `infra/cfn/cognito/cognito.yml` |16| Capabilities | none |17| Lifecycle | prepare (prerequisite stack) |18| Tier | cognito |1920## Parameters2122| Parameter | Type | Default | Validation | Error Message |23|-----------|------|---------|------------|---------------|24| Namespace | String | — | `/^[a-z][a-z0-9-]{0,11}$/` | "Invalid namespace — 1-12 chars, lowercase alphanumeric + hyphens, starts with letter" |25| Environment | String | — | `/^[a-z][a-z0-9-]{0,11}$/` | "Must be 1-12 chars, lowercase letters/digits/hyphens, starts with letter" |26| CallbackURL | String | `http://localhost:8080/authentication/callback` | `/^https?:\/\/.+$/` | "Must be a valid HTTP(S) URL" |27| CognitoDomainPrefix | String | — | `/^[a-z][a-z0-9-]{0,62}$/` | "Must be 1-63 lowercase chars, starts with letter, no reserved words (cognito, aws, amazon)" |2829**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.30| MinPasswordLength | Number | 8 | `8-99` | "Must be between 8 and 99" |31| DeletionProtection | String | INACTIVE | `ACTIVE \| INACTIVE` | "Must be ACTIVE or INACTIVE" |3233All parameters are **Configuration** type — sourced from `.env` or defaults. No wirable parameters from other stacks.3435## Outputs3637| Output | Description | Export Convention | Used By |38|--------|-------------|------------------|---------|39| UserPoolId | ID of the Cognito User Pool | `{StackName}-UserPoolId` | Admin operations |40| UserPoolArn | ARN of the Cognito User Pool | `{StackName}-UserPoolArn` | ipa-stack-backend (JWT authorizer), ipa-stack-queue (JWT authorizer) |41| UserPoolClientId | ID of the App Client | `{StackName}-UserPoolClientId` | ipa-stack-backend (AuthAudience), ipa-stack-queue (AuthAudience) |42| IssuerUrl | OIDC Issuer base URL | `{StackName}-IssuerUrl` | ipa-stack-backend (AuthIssuer), ipa-stack-queue (AuthIssuer) |43| EndSessionEndpoint | Cognito logout base URL | `{StackName}-EndSessionEndpoint` | Frontend OIDC config |44| HostedUIURL | Full Cognito login URL | `{StackName}-HostedUIURL` | Runbook reference |45| CognitoDomain | Domain prefix value | `{StackName}-CognitoDomain` | Frontend OIDC authority |46| DiscoveryUrl | OIDC Discovery URL | `{StackName}-DiscoveryUrl` | JWT validation libraries |4748## Security Summary4950**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/*`51**Security controls**: Advanced Security Mode ENFORCED, AdminCreateUserOnly, PreventUserExistenceErrors ENABLED, OAuth 2.0 Authorization Code Grant only52**Full advisory**: See [SECURITY.md](SECURITY.md)5354## Terraform Module5556| Property | Value |57|----------|-------|58| Module path | `infra/tf/cognito/` |59| State key | `{namespace}-{env}/cognito/terraform.tfstate` |60| Required version | `>= 1.5.0` |61| Providers | `hashicorp/aws >= 5.0` |6263### Variables6465| Variable | Type | Default | Maps to CFN |66|----------|------|---------|-------------|67| namespace | string | — | Namespace |68| environment | string | — | Environment |69| region | string | — | (implicit) |70| state_bucket | string | — | (TF infrastructure) |71| cognito_domain_prefix | string | — | CognitoDomainPrefix |72| callback_url | string | `http://localhost:8080/authentication/callback` | CallbackURL |7374### Outputs7576| Output | Maps to CFN |77|--------|-------------|78| user_pool_id | UserPoolId |79| user_pool_arn | UserPoolArn |80| user_pool_client_id | UserPoolClientId |81| issuer_url | IssuerUrl |82| end_session_endpoint | EndSessionEndpoint |83| cognito_domain | CognitoDomain |84| discovery_url | DiscoveryUrl |
aws-samples