User Pools

Userpools securely store your users and provide sign-up, sign-in, and access control for your applications.
Userpools support OAuth 2.0, SAML 2.0, and OpenID Connect standards.
Userpools can be integrated with HTTP API Gateways using authorizers to provide access only for authenticated users.

When to use

Userpools can be used almost anytime your application needs to authenticate and authorize users.

Advantages

Pay-per-MAU - You pay for Monthly Active Users.
Free-tier - There's a free tier of 50,000 MAUs for users who sign in directly to Cognito User Pools (not using SAML or OIDC federation).
Serverless - You can seamlessly scale your userbase almost indefinitely.
Secure by default - Your users are securely stored by AWS.
Compliant - With userpools, you are HIPAA eligible and PCI DSS, SOC, ISO/IEC 27001, ISO/IEC 27017, ISO/IEC 27018, and ISO 9001 compliant by default.

Disadvantages

Not cheap for large user bases - When you have more than 50,000 MAUs or many users with SAML or OIDC federation, can get expensive.
Not easy to understand - Similarly to almost everything related to authentication or OAUTH, understanding user pool authentication flows can be complicated.

Basic usage

Example: Lambda function connected to HTTP API Gateway with authorizer that allows only users authenticated using myUserPool to access the configured path.


resources:
  createPost:
    type: function
    properties:
      packageConfig:
        filePath: 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

API reference

UserAuthPool API reference

type

Required

No description

Type: string "user-auth-pool"

properties.allowOnlyAdminsToCreateAccount

Enusures that new accounts can only be created using admin create flows

Type: boolean

If this is disabled, users can sign themselves up.

properties.unusedAccountValidityDays

Maximum number of days that unused accounts will be preserved

Type: number

properties.requireEmailVerification

Enforces email verification for new accounts

Type: boolean

properties.requirePhoneNumberVerification

Enforces phone number verification for new accounts

Type: boolean

properties.hostedUiDomainPrefix

Domain prefix for the hosted UI

Type: string

properties.hostedUiCSS

CSS applied to your hosted UI

Type: string

properties.hooks

Function hooks that will be triggered on certain events that happen inside the userpool

Type: UserPoolHooks

To better understand user pool hooks, refer to AWS Docs

properties.emailConfiguration

Configuration for emails sent by Cognito User Pool

Type: EmailConfiguration

properties.inviteMessageConfig

Configuration of invite message for new users

Type: InviteMessageConfig

properties.userVerificationType

Configuration of user verification type

Type: string ENUM

Possible values: email-codeemail-linknonesms

none - no verification is required
email-link - user recieves a link that he needs to click via an email
email-code - user receives a code that he needs to enter via an email
sms - user receives a code that he needs to enter via a SMS

properties.userVerificationMessageConfig

Configures the user verification message

Type: UserVerificationMessageConfig

properties.mfaConfiguration

Configures Multi-factor Authentication for this userpool

Type: MfaConfiguration

properties.passwordPolicy

Requirements for the password

Type: PasswordPolicy

Applies for users created using directly using cognito

properties.schema

No description

Type: Array of AttributeSchema

properties.allowPhoneNumberAsUserName

Allows phone number to be used as a username

Type: boolean

properties.allowEmailAsUserName

Allows email to be used as a username

Type: boolean

properties.accessTokenValiditySeconds

Duration (in seconds) until the access token expires

Type: number

To better understand tokens used in in cognito user pools, refer to AWS docs

properties.idTokenValiditySeconds

Duration (in seconds) until the identity token expires

Type: number

To better understand tokens used in in cognito user pools, refer to AWS docs

properties.refreshTokenValidityDays

Duration (in seconds) until the refresh token expires

Type: number

To better understand tokens used in in cognito user pools, refer to AWS docs

properties.allowedOathFlows

Oauth flows allowed for this user pool

Type: Array of string ENUM

Possible values: client_credentialscodeimplicit

To better understand Oauth flows, refer to AWS blog post

properties.allowedOAuthScopes

Oauth scopes allowed for this user pool

Type: Array of string

properties.callbackURLs

User will be redirected to this URL after a successfull authentication

Type: Array of string

properties.logoutURLs

User will be redirected to this URL after a logout

Type: Array of string

properties.identityProviders

Configuration for external identity providers

Type: Array of IdentityProvider

overrides

Overrides one or more properties of the specified child resource.

Type: Object

Child resouces are specified using their descriptive name (e.g. DbInstance or Events.0.HttpApiRoute).
To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
To see the list of properties that can be overriden, refer to AWS Cloudformation docs.

UserPoolHooks API reference

Parent API reference: UserAuthPool

customMessage

No description

Type: string

postAuthentication

No description

Type: string

postConfirmation

No description

Type: string

preAuthentication

No description

Type: string

preSignUp

No description

Type: string

preTokenGeneration

No description

Type: string

userMigration

No description

Type: string

createAuthChallenge

No description

Type: string

defineAuthChallenge

No description

Type: string

verifyAuthChallengeResponse

No description

Type: string

EmailConfiguration API reference

Parent API reference: UserAuthPool

sesAddressArn

No description

Type: string

from

No description

Type: string

replyToEmailAddress

No description

Type: string

InviteMessageConfig API reference

Parent API reference: UserAuthPool

emailMessage

No description

Type: string

emailSubject

No description

Type: string

smsMessage

No description

Type: string

UserVerificationMessageConfig API reference

Parent API reference: UserAuthPool

emailMessageUsingCode

No description

Type: string

emailMessageUsingLink

No description

Type: string

emailSubjectUsingCode

No description

Type: string

emailSubjectUsingLink

No description

Type: string

smsMessage

No description

Type: string

MfaConfiguration API reference

Parent API reference: UserAuthPool

status

No description

Type: string ENUM

Possible values: OFFONOPTIONAL

enabledTypes

No description

Type: Array of string ENUM

Possible values: SMSSOFTWARE_TOKEN

PasswordPolicy API reference

Parent API reference: UserAuthPool

minimumLength

No description

Type: number

requireLowercase

No description

Type: boolean

requireNumbers

No description

Type: boolean

requireSymbols

No description

Type: boolean

requireUppercase

No description

Type: boolean

temporaryPasswordValidityDays

No description

Type: number

AttributeSchema API reference

Parent API reference: UserAuthPool

name

No description

Type: string

attributeDataType

No description

Type: string

developerOnlyAttribute

No description

Type: boolean

mutable

No description

Type: boolean

required

No description

Type: boolean

numberMaxValue

No description

Type: number

numberMinValue

No description

Type: number

stringMaxLength

No description

Type: number

stringMinLength

No description

Type: number

IdentityProvider API reference

Parent API reference: UserAuthPool

type

Required

No description

Type: string ENUM

Possible values: FacebookGoogleLoginWithAmazonOIDCSAMLSignInWithApple

clientId

Required

No description

Type: string

clientSecret

Required

No description

Type: string

attributeMapping

No description

Type: Object - { string : string }

authorizeScopes

No description

Type: Array of string

providerDetails

No description

Type: Object - { string : any }