CognitoUserPool

A Cognito user pool with a 12-character password policy, deletion protection and an app client. Add MFA, social login or SAML when you need them.

API & Auth · anvil:aws:CognitoUserPool

Arguments

Names below are TypeScript (camelCase). In Python use snake_case (e.g. dataClassification → data_classification); in Go use PascalCase on the Args struct (e.g. DataClassification).

appClient
object (CognitoUserPoolAppClient)

Default app client created with the user pool. Covers the 80% case of one application per pool. Use hatch for additional clients.

attributes
object (CognitoUserPoolAttributes)

User attribute configuration. Controls sign-in identifiers and required attributes on sign-up.

  • email— Users sign in with their email address.
  • phone_number— Users sign in with their phone number.
passwordPolicy
object (CognitoUserPoolPasswordPolicy)

Password policy for the user pool. Anvil enforces a secure baseline by default — override only to strengthen.

mfa
object (CognitoUserPoolMfa)

MFA configuration. TOTP requires no additional AWS resources. SMS requires an SNS caller ARN.

  • OFF— MFA disabled. Default.
  • OPTIONAL— MFA available but not required.
  • REQUIRED— MFA required for all users.
identityProviders
array

External identity providers to federate with this user pool.

  • Google— Google OAuth 2.0. Requires clientId and clientSecret.
  • Facebook— Facebook OAuth 2.0. Requires clientId and clientSecret.
  • LoginWithAmazon— Login with Amazon. Requires clientId and clientSecret.
  • SignInWithApple— Sign in with Apple. Requires clientId and clientSecret.
  • OIDC— Generic OIDC provider (Okta, Auth0, Microsoft Entra, etc). Requires clientId, clientSecret, and oidcIssuer.
  • SAML— SAML 2.0 provider (corporate SSO, AD FS, etc). Requires metadataUrl or metadataContent.
hostedUi
object (CognitoUserPoolHostedUi)

Hosted UI / Managed Login configuration. Omit to use the Cognito user pools API directly without a hosted sign-in page.

emailConfiguration
object (CognitoUserPoolEmailConfiguration)

Email delivery configuration. Default: Cognito-managed email (5 emails/day limit). Set sesFromAddress for SES delivery in production.

waf
object (CognitoUserPoolWaf)

Attaches a WAF to the user pool — AWS recommends one for every public pool (credential stuffing, brute force, bots, SMS pumping). arn (required): an Anvil Waf created with scope: "regional" in the same region as the pool.

appClient 7 fields

Default app client configuration. Covers the 80% case — one client per pool.

callbackUrls
array<string>

Allowed redirect URLs after successful sign-in. Required when using the hosted UI.

generateSecret
boolean

Generate a client secret. Required for confidential clients (server-side apps). Must NOT be set for SPAs — never expose secrets in browser code. Default: false.

logoutUrls
array<string>

Allowed redirect URLs after sign-out.

oauthFlows
array<string>

Allowed OAuth flows. Default: [code]. Use code (PKCE) for SPAs and server apps. client_credentials for M2M.

  • code— Authorization code grant (PKCE). Most secure — use for all browser and server apps.
  • implicit— Implicit grant. Deprecated — tokens visible in browser URL. Avoid for new applications.
  • client_credentials— Client credentials grant. M2M only — no user interaction.
oauthScopes
array<string>

OAuth scopes to allow. Default: [openid, email, profile].

supportedIdentityProviders
array<string>

Identity providers shown on the hosted UI login page for this client. Default: [COGNITO]. Add provider names from identityProviders here to show social login buttons.

tokenValidity
object (CognitoUserPoolTokenValidity)

Token validity periods. Anvil defaults: access 1h, id 1h, refresh 30d.

appClient.tokenValidity 3 fields

Token validity configuration.

accessTokenValidity
integer

Access token validity in hours. Default: 1.

idTokenValidity
integer

ID token validity in hours. Default: 1.

refreshTokenValidity
integer

Refresh token validity in days. Default: 30.

attributes 3 fields

User attribute and sign-in configuration.

customAttributes
array (CognitoUserPoolCustomAttribute)

Custom attributes to add to user profiles. Cannot be deleted after pool creation.

requiredAttributes
array<string>

Standard attributes required on sign-up. Default: [email]. Cannot be changed after pool creation.

usernameAttributes
array<string>

Attributes users can sign in with. Default: [email]. Set to [phone_number] or [email, phone_number] to allow both. Cannot be changed after pool creation.

  • email— Users sign in with their email address.
  • phone_number— Users sign in with their phone number.
attributes.customAttributes[] 3 fields

A custom attribute to add to user profiles.

name required
string

Attribute name. Cognito prefixes this with 'custom:' automatically.

mutable
boolean

Whether the attribute can be changed after a user is created. Default: true.

type
string

Attribute data type. Default: String.

  • String
  • Number
  • DateTime
  • Boolean
emailConfiguration 2 fields

Email delivery configuration. Default uses Cognito-managed email which has a 50 emails/day limit. Configure SES for production workloads.

replyToAddress
string

Reply-to address shown in outgoing emails. Optional.

sesFromAddress
string

Verified SES sender address (e.g. [email protected]). Setting this switches delivery to SES, removing the 50 emails/day limit. The address must be verified in SES in the same region as the user pool.

hostedUi 3 fields

Hosted UI (Managed Login) configuration. Enables the Cognito-hosted sign-in page.

domain required
string

Domain for the hosted UI. For Cognito-managed domains, provide just the prefix (e.g. 'myapp' → myapp.auth.{region}.amazoncognito.com). For custom domains, provide the fully-qualified domain name (e.g. 'auth.myapp.com'). Required.

acmCertificateArn
string

ACM certificate ARN for the custom domain. Must be in us-east-1 regardless of user pool region — this is a hard AWS requirement. Required when customDomain is true.

customDomain
boolean

Set to true when domain is a custom FQDN you own. Requires acmCertificateArn. Anvil creates the CloudFront distribution and wires the alias automatically. Default: false.

identityProviders[] 8 fields

An external identity provider to federate with this user pool. Discriminated by type — the same schema covers all provider types. Add new providers by extending the identityProviders array, no schema changes required.

type required
string

Provider type. Determines which fields are required. Google/Facebook/LoginWithAmazon/SignInWithApple require clientId and clientSecret. OIDC additionally requires oidcIssuer. SAML requires metadataUrl or metadataContent.

  • Google— Google OAuth 2.0. Requires clientId and clientSecret.
  • Facebook— Facebook OAuth 2.0. Requires clientId and clientSecret.
  • LoginWithAmazon— Login with Amazon. Requires clientId and clientSecret.
  • SignInWithApple— Sign in with Apple. Requires clientId and clientSecret.
  • OIDC— Generic OIDC provider (Okta, Auth0, Microsoft Entra, etc.). Requires clientId, clientSecret, and oidcIssuer.
  • SAML— SAML 2.0 provider (corporate SSO, Active Directory Federation Services etc.). Requires metadataUrl or metadataContent.
attributeMapping
map<string, string>

Maps Cognito user attributes to provider-specific claim names. Key is the Cognito attribute (e.g. 'email'), value is the provider claim (e.g. 'email' for Google, or the full SAML attribute URI for SAML providers).

clientId
string

OAuth client ID from the identity provider. Required for Google, Facebook, LoginWithAmazon, SignInWithApple, OIDC.

clientSecret
string

OAuth client secret from the identity provider. Required for Google, Facebook, LoginWithAmazon, OIDC. Not used for SAML.

metadataContent
string

Inline SAML metadata XML. Required for SAML when metadataUrl is not provided.

metadataUrl
string

URL of the SAML metadata document. Required for SAML when metadataContent is not provided.

name
string

Friendly name for this provider. Required for OIDC and SAML providers. Optional for well-known social providers (Google, Facebook etc.) — defaults to the type name.

oidcIssuer
string

OIDC issuer URL. Required when type is OIDC. Cognito fetches the discovery document from {oidcIssuer}/.well-known/openid-configuration.

mfa 3 fields

MFA configuration for the user pool.

methods
array<string>

MFA methods to enable. TOTP requires no additional AWS resources. SMS requires snsCallerArn.

  • TOTP— Time-based one-time password (authenticator app). No additional AWS resources required.
  • SMS— SMS one-time password via SNS. Requires snsCallerArn.
mode
string

MFA enforcement mode. Default: OFF.

  • OFF— MFA disabled. Default.
  • OPTIONAL— MFA available but not required. Users opt in.
  • REQUIRED— MFA required for all users.
snsCallerArn
string

ARN of the IAM role Cognito uses to send SMS messages via SNS. Required when methods includes SMS. Anvil will create this role automatically if omitted and SMS is enabled.

passwordPolicy 6 fields

Password policy for the user pool. Anvil defaults satisfy CIS Benchmarks and SOC 2 baseline.

minLength
integer

Minimum password length. Default: 12. Minimum allowed: 6.

requireLowercase
boolean

Require at least one lowercase letter. Default: true.

requireNumbers
boolean

Require at least one number. Default: true.

requireSymbols
boolean

Require at least one symbol. Default: true.

requireUppercase
boolean

Require at least one uppercase letter. Default: true.

temporaryPasswordValidityDays
integer

Number of days a temporary password is valid. Default: 7.

waf 1 field

Attaches a WAF to the user pool.

arn required
string

ARN of a regional-scope WebACL in the same region as the pool. Pass waf.arn from an Anvil Waf with scope "regional".

This component also accepts a hatch argument to override the underlying resource configuration. See Overrides & Escape Hatch.

Attributes

Outputs available once the resource is deployed.

userPoolId
string

The Cognito user pool ID. Pass to CognitoAuth.userPoolId.

userPoolArn
string

The ARN of the Cognito user pool.

appClientId
string

The ID of the default app client. Pass to CognitoAuth.audience.

appClientSecret
string

The client secret of the default app client. Only populated when appClient.generateSecret is true. Treat as sensitive.

endpoint
string

The Cognito OIDC issuer URL. Pass directly to CognitoAuth if building the authorizer manually.

hostedUiDomain
string

The full hosted UI domain. Empty string if hostedUi is not configured.

cloudFrontDomain
string

The CloudFront distribution domain for the custom hosted UI. Only populated when hostedUi.customDomain is true.