logoStacktape docs




User Pools

Overview and basic concepts

  • 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.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

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 }