User Authentication (Cognito)



User pools provide a secure identity store for your users, handling sign-up, sign-in, and access control for your applications. They support standard identity protocols like OAuth 2.0, SAML 2.0, and OpenID Connect, and can be integrated with HTTP API Gateways to protect your endpoints.

When to use them

User pools are a good choice whenever your application needs to authenticate and authorize users.


Advantages

  • Pay-per-MAU: You pay for monthly active users.
  • Free tier: The first 50,000 monthly active users are free (for users who sign in directly, not through SAML or OIDC federation).
  • Serverless: Scales seamlessly to handle a large number of users.
  • Secure by default: User data is stored securely by AWS.
  • Compliant: User pools are HIPAA eligible and compliant with PCI DSS, SOC, ISO/IEC 27001, and other standards.

Disadvantages

  • Cost at scale: Can become expensive for large user bases or heavy use of SAML or OIDC federation.
  • Complexity: Authentication flows and standards like OAuth can be complex to understand and implement correctly.

Basic usage

This example shows a Lambda function connected to an HTTP API Gateway with an authorizer that only allows access to users authenticated by myUserPool.

resources:
  createPost:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: src/index.ts
      events:
        - type: http-api-gateway
          properties:
            httpApiGatewayName: myGateway
            path: /post/create
            method: POST
            authorizer:
              type: cognito
              properties:
                userPoolName: myUserPool

  myUserPool:
    type: user-auth-pool
    properties:
      userVerificationType: email-code
      passwordPolicy:
        minimumLength: 8

Password policy

You can enforce a password policy for your users, specifying minimum length and requiring lowercase letters, numbers, symbols, and uppercase letters.

PasswordPolicyAPI referenceParent:UserAuthPool
minimumLength

Minimum password length

The fewest characters a password can have. Longer passwords are generally more secure.

Type: number

requireLowercase

Require at least one lowercase letter

Type: boolean

requireNumbers

Require at least one number

Type: boolean

requireSymbols

Require at least one symbol

Symbols are non‑alphanumeric characters such as !, @, or #.

Type: boolean

requireUppercase

Require at least one uppercase letter

Type: boolean

temporaryPasswordValidityDays

Temporary password validity (days)

How long a temporary password issued to a new user is valid before it must be changed on first sign‑in.

Type: number

Multi-factor authentication

You can enable multi-factor authentication (MFA) for your user pool to add an extra layer of security.

MfaConfigurationAPI referenceParent:UserAuthPool
status

MFA requirement

  • OFF: MFA is completely disabled.
  • ON: All users must complete MFA during sign‑in.
  • OPTIONAL: Users can opt in to MFA; it's recommended but not strictly required.

This value configures the Cognito MfaConfiguration property.

Type: string ENUM

Possible values: OFFONOPTIONAL

enabledTypes

Enabled MFA factor types

Type: Array of string ENUM

Possible values: EMAIL_OTPSMSSOFTWARE_TOKEN

Chooses which MFA methods users can use:

  • SMS: One‑time codes are sent via text message. Requires an SNS role so Cognito can send SMS.
  • SOFTWARE_TOKEN: Time‑based one‑time codes from an authenticator app.
  • EMAIL_OTP: Codes are sent by email. AWS requires that you configure a developer email sending identity (which Stacktape does when you provide emailConfiguration.sesAddressArn).

These values are mapped to Cognito's EnabledMfas setting (SMS_MFA, SOFTWARE_TOKEN_MFA, EMAIL_OTP), whose behavior is described in EnabledMfas in the AWS::Cognito::UserPool docs.

Hooks

You can use Lambda functions as hooks to trigger custom logic at different points in the user authentication lifecycle, such as before sign-up or after a successful sign-in.

UserPoolHooksAPI referenceParent:UserAuthPool
customMessage

Custom message hook

Triggered whenever Cognito is about to send an email or SMS (sign‑up, verification, password reset, etc.). Lets you fully customize message contents or dynamically choose language/branding.

Value must be the ARN of a Lambda function configured to handle the "Custom Message" trigger.

Type: string

postAuthentication

Post-authentication hook

Runs after a user has successfully authenticated. You can use this to record analytics, update last‑login timestamps, or block access based on additional checks.

Type: string

postConfirmation

Post-confirmation hook

Runs right after a user confirms their account (for example via email link or admin confirmation). This is often used to create user records in your own database or to provision resources.

Type: string

preAuthentication

Pre-authentication hook

Invoked just before Cognito validates a user's credentials. You can use this to block sign‑in attempts based on IP, device, or user state (for example, soft‑deleting an account).

Type: string

preSignUp

Pre-sign-up hook

Called before a new user is created. Useful for validating input, auto‑confirming trusted users, or blocking sign‑ups that don't meet your business rules.

Type: string

preTokenGeneration

Pre-token-generation hook

Runs right before Cognito issues tokens. Lets you customize token claims (for example, adding roles or flags) based on external systems or additional logic.

Type: string

userMigration

User migration hook

Lets you migrate users on‑the‑fly from another user store. When someone tries to sign in but doesn't exist in Cognito, this trigger can look them up elsewhere, import them, and let the sign‑in continue.

Type: string

createAuthChallenge

Create auth challenge hook

Part of Cognito's custom auth flow. This trigger is used to generate a challenge (for example sending a custom OTP) after DefineAuthChallenge decides a challenge is needed.

Type: string

defineAuthChallenge

Define auth challenge hook

Also part of the custom auth flow. It decides whether a user needs another challenge, has passed, or has failed, based on previous challenges and responses.

Type: string

verifyAuthChallengeResponse

Verify auth challenge response hook

Validates the user's response to a custom challenge (for example, checking an OTP the user provides).

Type: string

External identity providers

You can allow users to sign in with external identity providers like Google, Facebook, or any SAML or OIDC-compliant provider.

IdentityProviderAPI referenceParent:UserAuthPool
typeRequired

Provider type

Type: string ENUM

Possible values: FacebookGoogleLoginWithAmazonOIDCSAMLSignInWithApple

The kind of external identity provider you want to integrate:

  • Facebook, Google, LoginWithAmazon, SignInWithApple: social identity providers.
  • OIDC: a generic OpenID Connect provider.
  • SAML: a SAML 2.0 identity provider (often used for enterprise SSO).
clientIdRequired

OAuth / OIDC client ID

Type: string

The client ID (sometimes called app ID) that you obtained from the external provider's console. Cognito presents this ID when redirecting users to the provider.

clientSecretRequired

OAuth / OIDC client secret

Type: string

The client secret associated with the clientId, used by Cognito when exchanging authorization codes for tokens. This value should be kept confidential and only configured from secure sources.

attributeMapping

Attribute mapping

Type: Object

Maps attributes from the external provider (for example email, given_name) to Cognito user pool attributes. Keys are Cognito attribute names, values are attribute names from the identity provider.

If not provided, Stacktape defaults to mapping email -> email.

authorizeScopes

Requested scopes

Type: Array of string

Additional OAuth scopes to request from the identity provider (for example openid, email, profile). These control which pieces of user information and permissions your app receives in the provider's tokens.

If omitted, Stacktape uses a reasonable default per provider (see AWS::Cognito::UserPoolIdentityProvider).

providerDetails

Advanced provider options

Type: Object - { string : any }

Low‑level configuration passed directly into Cognito's ProviderDetails map. You can use this to override endpoints or supply provider‑specific keys as documented by AWS, for example authorize_url, token_url, attributes_request_method, oidc_issuer, and others.

In most cases you don't need to set this – Stacktape configures sensible defaults for common providers.

Firewall

You can protect your user pool with a web application firewall.

Links the user pool to a web-app-firewall resource, so requests to the Hosted UI and token endpoints are inspected by AWS WAF rules you configure in Stacktape.

Stacktape does this by creating a WebACLAssociation between the user pool and the referenced firewall.

To learn more, see the Web Application Firewall documentation.

resources:
  myFirewall:
    type: web-app-firewall
    properties:
      scope: regional
  myUserPool:
    type: user-auth-pool
    properties:
      userVerificationType: email-code
      passwordPolicy:
        minimumLength: 8
      useFirewall: myFirewall

Pricing

Amazon Cognito has a free tier for user pools, which includes 10,000 monthly active users (MAUs) for users who sign in directly or through a social identity provider. For users who sign in through SAML or OIDC federation, the free tier includes 50 MAUs.

Beyond the free tier, pricing is based on the number of MAUs. For the "Lite" tier, the costs are as follows:

  • 10,001 - 100,000 MAUs: $0.0055 per MAU
  • 100,001 - 1,000,000 MAUs: $0.0046 per MAU
  • Over 1,000,000 MAUs: $0.00325 per MAU

For users federated through SAML or OIDC, the price is $0.015 per MAU above the free tier.

Additional charges apply for sending SMS messages for MFA and for using advanced security features. For detailed and up-to-date pricing information, see the Amazon Cognito pricing page.

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

id
  • Id of the userpool

  • Usage: $ResourceParam('<<resource-name>>', 'id')
clientId
  • Id of the userpool

  • Usage: $ResourceParam('<<resource-name>>', 'clientId')
domain
  • Domain of the userpool

  • Usage: $ResourceParam('<<resource-name>>', 'domain')

API reference

UserAuthPoolAPI reference
typeRequired
No description

Type: string "user-auth-pool"

properties.allowOnlyAdminsToCreateAccount

Restrict account creation to administrators

Type: boolean

If enabled, new users can't sign up themselves. Accounts must be created through an admin flow (for example from an internal admin tool or script), which helps prevent unwanted self-registrations.

Internally this controls AdminCreateUserConfig.AllowAdminCreateUserOnly on the Cognito user pool (AWS::Cognito::UserPool).

properties.unusedAccountValidityDaysDefault: 31

Expire unused admin-created accounts

Type: number

When an admin creates a user account, Cognito issues a temporary password. This setting controls how many days that temporary password (and the corresponding account) stays valid if the user never signs in.

Internally this maps to AdminCreateUserConfig.UnusedAccountValidityDays.

properties.requireEmailVerification

(Reserved) Require verified emails

Type: boolean

Present for forward compatibility. Stacktape currently derives email / phone verification behavior from userVerificationType, not from this flag directly.

To require email-based verification today, use userVerificationType: 'email-link' | 'email-code' instead.

properties.requirePhoneNumberVerification

(Reserved) Require verified phone numbers

Type: boolean

Present for forward compatibility. Stacktape currently derives email / phone verification behavior from userVerificationType, not from this flag directly.

To require SMS-based verification today, use userVerificationType: 'sms'.

properties.enableHostedUi

Enable the Cognito Hosted UI

Type: boolean

Turns on Cognito's Hosted UI – a pre-built, hosted login and registration page – so you don't have to build your own auth screens. This is useful when you want to get started quickly or keep authentication logic outside of your main app.

properties.hostedUiDomainPrefix

Hosted UI domain prefix

Type: string

Sets the first part of your Hosted UI URL: https://.auth..amazoncognito.com. Pick something that matches your project or company name.

properties.hostedUiCSS

Custom CSS for the Hosted UI

Type: string

Lets you override the default Cognito Hosted UI styling with your own CSS (colors, fonts, layouts, etc.), so the login experience matches the rest of your application.

Behind the scenes this is applied using the AWS::Cognito::UserPoolUICustomizationAttachment resource.

properties.hooks

Lambda triggers for the user pool

Type: UserPoolHooks

Connects AWS Lambda functions to Cognito "hooks" (triggers) such as pre-sign-up, post-confirmation, or token generation. You can use these to enforce additional validation, enrich user profiles, migrate users from another system, and more.

Internally this maps to the Cognito user pool LambdaConfig.

properties.emailConfiguration

Email delivery settings

Type: EmailConfiguration

Controls how Cognito sends emails (verification messages, password reset codes, admin invitations, etc.). You can either use Cognito's built-in email service or plug in your own SES identity for full control over the sender.

This config is used to build the Cognito EmailConfiguration block (AWS docs).

properties.inviteMessageConfig

Invite message overrides

Type: InviteMessageConfig

Customizes the contents of the "invitation" message that users receive when an administrator creates their account (for example, when sending a temporary password and sign-in instructions).

If you want to send custom emails through SES, you must also configure emailConfiguration.sesAddressArn.

properties.userVerificationType

Verification strategy

Type: string ENUM

Possible values: email-codeemail-linknonesms

Chooses how new users prove that they own their contact information:

  • email-link: Cognito emails a clickable link.
  • email-code: Cognito emails a short numeric code.
  • sms: Cognito sends a code via SMS to the user's phone number.
  • none: Users aren't required to verify email or phone during sign-up.

Stacktape uses this value to configure AutoVerifiedAttributes and VerificationMessageTemplate on the underlying Cognito user pool.

properties.userVerificationMessageConfig

Verification message text

Type: UserVerificationMessageConfig

Lets you customize the exact email and SMS texts that Cognito sends when asking users to verify their email / phone. For example, you can change subjects, body text, or the message that contains the {####} verification code.

properties.mfaConfiguration

Multi-factor authentication

Type: MfaConfiguration

Controls whether you use Multi‑Factor Authentication (MFA) and which second factors are allowed. MFA makes it much harder for attackers to access accounts even if they know a user's password.

Under the hood this config drives both the MfaConfiguration and EnabledMfas properties in Cognito (see "MFA configuration" in the AWS::Cognito::UserPool docs).

properties.passwordPolicy

Password strength rules

Type: PasswordPolicy

Defines how strong user passwords must be – minimum length and whether they must include lowercase, uppercase, numbers, and/or symbols – plus how long temporary passwords issued to new users remain valid.

This is applied to the Cognito Policies.PasswordPolicy block.

properties.schema

Custom attributes schema

Type: Array of AttributeSchema

Lets you define additional attributes (like role, plan, companyId, etc.) that are stored on each user, including their data type and validation constraints.

These translate into the Cognito user pool Schema entries (schema docs).

properties.allowPhoneNumberAsUserNameDefault: true

Allow phone numbers as usernames

Type: boolean

If enabled (the default), users can sign in using their phone number in addition to any traditional username. Turning this off means phone numbers can still be stored, but can't be used to log in.

This is implemented via Cognito's UsernameAttributes configuration.

properties.allowEmailAsUserNameDefault: true

Allow email addresses as usernames

Type: boolean

If enabled (the default), users can sign in using their email address instead of a dedicated username. Turning this off means emails can still be stored, but can't be used to log in directly.

This is also controlled through Cognito UsernameAttributes.

properties.accessTokenValiditySeconds

Access token lifetime

Type: number

Controls how long an access token issued by Cognito stays valid after login. Shorter lifetimes reduce the window in which a stolen token can be abused, at the cost of more frequent refreshes.

This value is passed to the user pool client as AccessTokenValidity.

properties.idTokenValiditySeconds

ID token lifetime

Type: number

Controls how long an ID token (which contains user profile and claims) is accepted before clients must obtain a new one.

This is set on the user pool client as IdTokenValidity.

properties.refreshTokenValidityDays

Refresh token lifetime

Type: number

Sets for how many days a refresh token can be used to obtain new access / ID tokens without requiring the user to sign in again. Longer lifetimes mean fewer re-authentications, but keep sessions alive for longer.

This value is used as RefreshTokenValidity on the Cognito user pool client.

properties.allowedOAuthFlows

OAuth flows

Type: Array of string ENUM

Possible values: client_credentialscodeimplicit

Specifies which OAuth 2.0 flows the user pool client is allowed to use:

  • code: Authorization Code flow (recommended for web apps and backends).
  • implicit: Implicit flow (legacy browser-only flow).
  • client_credentials: Server‑to‑server (no end user) machine credentials.

These values populate AllowedOAuthFlows on the Cognito user pool client (AWS::Cognito::UserPoolClient).

properties.allowedOAuthScopes

OAuth scopes

Type: Array of string

Lists which scopes clients can request when using OAuth (for example email, openid, profile). Scopes control which user information and permissions your app receives in tokens.

These values are passed to the user pool client as AllowedOAuthScopes.

properties.callbackURLs

OAuth callback URLs

Type: Array of string

The allowed URLs where Cognito is permitted to redirect users after successful authentication. These must exactly match the URLs registered with your frontend / backend, otherwise the redirect will fail.

Mapped into CallbackURLs and DefaultRedirectURI on the user pool client.

properties.logoutURLs

OAuth logout URLs

Type: Array of string

The URLs Cognito can redirect users to after they log out of the Hosted UI or end their session. Must also be explicitly configured so that sign-out redirects don't fail.

These populate the LogoutURLs list on the user pool client.

properties.identityProviders

External identity providers

Type: Array of IdentityProvider

Allows users to sign in with third‑party identity providers like Google, Facebook, Login with Amazon, OIDC, SAML, or Sign in with Apple. Each entry configures one external provider (client ID/secret, attribute mapping, requested scopes, and advanced provider‑specific options).

Under the hood Stacktape creates separate AWS::Cognito::UserPoolIdentityProvider resources and registers them in the user pool client's SupportedIdentityProviders.

properties.useFirewall

Associate a WAF

Type: string

Links the user pool to a web-app-firewall resource, so requests to the Hosted UI and token endpoints are inspected by AWS WAF rules you configure in Stacktape.

Stacktape does this by creating a WebACLAssociation between the user pool and the referenced firewall.

properties.customDomain

Custom Domain

Type: UserPoolCustomDomainConfiguration

Configures a custom domain for the Cognito Hosted UI (e.g., auth.example.com).

When configured, Cognito creates a CloudFront distribution to serve your custom domain. Stacktape automatically:

  • Configures the user pool domain with your custom domain and an ACM certificate from us-east-1
  • Creates a DNS record pointing to the CloudFront distribution

The domain must be registered and verified in your Stacktape account with a valid ACM certificate in us-east-1.

properties.generateClientSecret

Generate a client secret

Type: boolean

Asks Cognito to generate a secret for the user pool client. Use this when you have trusted backends (like APIs or server‑side apps) that can safely store a client secret and use confidential OAuth flows.

This flag controls the GenerateSecret property on the user pool client.

properties.allowOnlyExternalIdentityProviders

Force external identity providers

Type: boolean

If true, users can't sign in with a username/password against the Cognito user directory at all. Instead, they must always use one of the configured external identity providers (Google, SAML, etc.).

Internally this removes COGNITO from SupportedIdentityProviders on the user pool client.

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true
UserPoolHooksAPI referenceParent:UserAuthPool
customMessage

Custom message hook

Triggered whenever Cognito is about to send an email or SMS (sign‑up, verification, password reset, etc.). Lets you fully customize message contents or dynamically choose language/branding.

Value must be the ARN of a Lambda function configured to handle the "Custom Message" trigger.

Type: string

postAuthentication

Post-authentication hook

Runs after a user has successfully authenticated. You can use this to record analytics, update last‑login timestamps, or block access based on additional checks.

Type: string

postConfirmation

Post-confirmation hook

Runs right after a user confirms their account (for example via email link or admin confirmation). This is often used to create user records in your own database or to provision resources.

Type: string

preAuthentication

Pre-authentication hook

Invoked just before Cognito validates a user's credentials. You can use this to block sign‑in attempts based on IP, device, or user state (for example, soft‑deleting an account).

Type: string

preSignUp

Pre-sign-up hook

Called before a new user is created. Useful for validating input, auto‑confirming trusted users, or blocking sign‑ups that don't meet your business rules.

Type: string

preTokenGeneration

Pre-token-generation hook

Runs right before Cognito issues tokens. Lets you customize token claims (for example, adding roles or flags) based on external systems or additional logic.

Type: string

userMigration

User migration hook

Lets you migrate users on‑the‑fly from another user store. When someone tries to sign in but doesn't exist in Cognito, this trigger can look them up elsewhere, import them, and let the sign‑in continue.

Type: string

createAuthChallenge

Create auth challenge hook

Part of Cognito's custom auth flow. This trigger is used to generate a challenge (for example sending a custom OTP) after DefineAuthChallenge decides a challenge is needed.

Type: string

defineAuthChallenge

Define auth challenge hook

Also part of the custom auth flow. It decides whether a user needs another challenge, has passed, or has failed, based on previous challenges and responses.

Type: string

verifyAuthChallengeResponse

Verify auth challenge response hook

Validates the user's response to a custom challenge (for example, checking an OTP the user provides).

Type: string

EmailConfigurationAPI referenceParent:UserAuthPool
sesAddressArn

SES identity to send emails from

Type: string

ARN of an SES verified identity (email address or domain) that Cognito should use when sending emails. Required when you want full control over sending (for example for MFA via EMAIL_OTP), because Cognito must switch into DEVELOPER email sending mode.

from

From address

Type: string

The email address that appears in the "From" field of messages sent by Cognito (if you're using SES). This address must be verified in SES if you're sending through your own identity.

replyToEmailAddress

Reply-to address

Type: string

Optional address where replies to Cognito emails should be delivered. If not set, replies go to the from address (or the default Cognito sender).

InviteMessageConfigAPI referenceParent:UserAuthPool
emailMessage

Invitation email body

Type: string

The text of the email sent when an administrator creates a new user. You can reference placeholders like {username} and {####} (temporary password or code) in the message.

emailSubject

Invitation email subject

Type: string

smsMessage

Invitation SMS body

Type: string

The content of the SMS message sent when new users are created with a phone number. As with email, you can include placeholders such as {username} and {####}.

UserVerificationMessageConfigAPI referenceParent:UserAuthPool
emailMessageUsingCode

Email body when verifying with a code

Used when userVerificationType is email-code. The message typically contains a {####} placeholder that Cognito replaces with a one‑time verification code.

Type: string

emailMessageUsingLink

Email body when verifying with a link

Used when userVerificationType is email-link. Cognito replaces special markers like {##verify your email##} with a clickable URL.

Type: string

emailSubjectUsingCode

Email subject when verifying with a code

Type: string

emailSubjectUsingLink

Email subject when verifying with a link

Type: string

smsMessage

SMS verification message

Type: string

Text of the SMS Cognito sends when verifying a phone number (for example containing {####}).

MfaConfigurationAPI referenceParent:UserAuthPool
status

MFA requirement

  • OFF: MFA is completely disabled.
  • ON: All users must complete MFA during sign‑in.
  • OPTIONAL: Users can opt in to MFA; it's recommended but not strictly required.

This value configures the Cognito MfaConfiguration property.

Type: string ENUM

Possible values: OFFONOPTIONAL

enabledTypes

Enabled MFA factor types

Type: Array of string ENUM

Possible values: EMAIL_OTPSMSSOFTWARE_TOKEN

Chooses which MFA methods users can use:

  • SMS: One‑time codes are sent via text message. Requires an SNS role so Cognito can send SMS.
  • SOFTWARE_TOKEN: Time‑based one‑time codes from an authenticator app.
  • EMAIL_OTP: Codes are sent by email. AWS requires that you configure a developer email sending identity (which Stacktape does when you provide emailConfiguration.sesAddressArn).

These values are mapped to Cognito's EnabledMfas setting (SMS_MFA, SOFTWARE_TOKEN_MFA, EMAIL_OTP), whose behavior is described in EnabledMfas in the AWS::Cognito::UserPool docs.

PasswordPolicyAPI referenceParent:UserAuthPool
minimumLength

Minimum password length

The fewest characters a password can have. Longer passwords are generally more secure.

Type: number

requireLowercase

Require at least one lowercase letter

Type: boolean

requireNumbers

Require at least one number

Type: boolean

requireSymbols

Require at least one symbol

Symbols are non‑alphanumeric characters such as !, @, or #.

Type: boolean

requireUppercase

Require at least one uppercase letter

Type: boolean

temporaryPasswordValidityDays

Temporary password validity (days)

How long a temporary password issued to a new user is valid before it must be changed on first sign‑in.

Type: number

AttributeSchemaAPI referenceParent:UserAuthPool
name

Attribute name

The logical name of the attribute as it appears on the user (for example given_name, plan, or tenantId).

Type: string

attributeDataType

Attribute data type

The value type stored for this attribute (String, Number, etc.). This is passed to Cognito's AttributeDataType.

Type: string

developerOnlyAttribute

Developer-only attribute

If true, the attribute is only readable/writable by privileged backend code and not exposed to end users directly.

Type: boolean

mutable

Mutable after sign-up

Controls whether the attribute can be changed after it has been initially set.

Type: boolean

required

Required at sign-up

If true, users must supply this attribute when creating an account.

Type: boolean

numberMaxValue

Maximum numeric value

Type: number

numberMinValue

Minimum numeric value

Type: number

stringMaxLength

Maximum string length

Type: number

stringMinLength

Minimum string length

Type: number

IdentityProviderAPI referenceParent:UserAuthPool
typeRequired

Provider type

Type: string ENUM

Possible values: FacebookGoogleLoginWithAmazonOIDCSAMLSignInWithApple

The kind of external identity provider you want to integrate:

  • Facebook, Google, LoginWithAmazon, SignInWithApple: social identity providers.
  • OIDC: a generic OpenID Connect provider.
  • SAML: a SAML 2.0 identity provider (often used for enterprise SSO).
clientIdRequired

OAuth / OIDC client ID

Type: string

The client ID (sometimes called app ID) that you obtained from the external provider's console. Cognito presents this ID when redirecting users to the provider.

clientSecretRequired

OAuth / OIDC client secret

Type: string

The client secret associated with the clientId, used by Cognito when exchanging authorization codes for tokens. This value should be kept confidential and only configured from secure sources.

attributeMapping

Attribute mapping

Type: Object

Maps attributes from the external provider (for example email, given_name) to Cognito user pool attributes. Keys are Cognito attribute names, values are attribute names from the identity provider.

If not provided, Stacktape defaults to mapping email -> email.

authorizeScopes

Requested scopes

Type: Array of string

Additional OAuth scopes to request from the identity provider (for example openid, email, profile). These control which pieces of user information and permissions your app receives in the provider's tokens.

If omitted, Stacktape uses a reasonable default per provider (see AWS::Cognito::UserPoolIdentityProvider).

providerDetails

Advanced provider options

Type: Object - { string : any }

Low‑level configuration passed directly into Cognito's ProviderDetails map. You can use this to override endpoints or supply provider‑specific keys as documented by AWS, for example authorize_url, token_url, attributes_request_method, oidc_issuer, and others.

In most cases you don't need to set this – Stacktape configures sensible defaults for common providers.