/terraform-aws-cognito-user-pool

Terraform module to create Amazon Cognito User Pools, configure its attributes and resources such as app clients, domain, resource servers. Amazon Cognito User Pools provide a secure user directory that scales to hundreds of millions of users.

Primary LanguageHCLApache License 2.0Apache-2.0

Terraform

terraform-aws-cognito-user-pool

Terraform module to create Amazon Cognito User Pools, configure its attributes and resources such as app clients, domain, resource servers. Amazon Cognito User Pools provide a secure user directory that scales to hundreds of millions of users. As a fully managed service, User Pools are easy to set up without any worries about standing up server infrastructure.

Usage

You can use this module to create a Cognito User Pool using the default values or use the detailed definition to set every aspect of the Cognito User Pool

Check the examples where you can see the simple example using the default values, the simple_extended version which adds  app clients, domain, resource servers resources, or the complete version with a detailed example.

Example (simple)

This simple example creates a AWS Cognito User Pool with the default values:

module "aws_cognito_user_pool_simple" {

  source  = "lgallard/cognito-user-pool/aws"

  user_pool_name = "mypool"

  tags = {
    Owner       = "infra"
    Environment = "production"
    Terraform   = true
  }

Example (complete)

This more complete example creates a AWS Cognito User Pool using a detailed configuration. Please check the example folder to get the example with all options:

module "aws_cognito_user_pool_complete" {

  source  = "lgallard/cognito-user-pool/aws"

  user_pool_name           = "mypool"
  alias_attributes         = ["email", "phone_number"]
  auto_verified_attributes = ["email"]

  admin_create_user_config = {
    email_subject = "Here, your verification code baby"
  }

  email_configuration = {
    email_sending_account  = "DEVELOPER"
    reply_to_email_address = "email@example.com"
    source_arn             = "arn:aws:ses:us-east-1:888888888888:identity/example.com"
  }

  password_policy = {
    minimum_length    = 10
    require_lowercase = false
    require_numbers   = true
    require_symbols   = true
    require_uppercase = true
  }

  schemas = [
    {
      attribute_data_type      = "Boolean"
      developer_only_attribute = false
      mutable                  = true
      name                     = "available"
      required                 = false
    },
    {
      attribute_data_type      = "Boolean"
      developer_only_attribute = true
      mutable                  = true
      name                     = "registered"
      required                 = false
    }
  ]

  string_schemas = [
    {
      attribute_data_type      = "String"
      developer_only_attribute = false
      mutable                  = false
      name                     = "email"
      required                 = true

      string_attribute_constraints = {
        min_length = 7
        max_length = 15
      }
    }
  ]

  tags = {
    Owner       = "infra"
    Environment = "production"
    Terraform   = true
  }

Providers

Name Version
aws >= 2.54.0

Inputs

Name Description Type Default Required
admin_create_user_config The configuration for AdminCreateUser requests map {} no
admin_create_user_config_allow_admin_create_user_only Set to True if only the administrator is allowed to create user profiles. Set to False if users can sign themselves up via an app bool true no
admin_create_user_config_email_message The message template for email messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively string "{username}, your verification code is {####}" no
admin_create_user_config_email_subject The subject line for email messages string "Your verification code" no
admin_create_user_config_sms_message - The message template for SMS messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively string "Your username is {username} and temporary password is {####}" no
alias_attributes Attributes supported as an alias for this user pool. Possible values: phone_number, email, or preferred_username. Conflicts with username_attributes list n/a yes
auto_verified_attributes The attributes to be auto-verified. Possible values: email, phone_number list [] no
client_allowed_oauth_flows The name of the application client list [] no
client_allowed_oauth_flows_user_pool_client Whether the client is allowed to follow the OAuth protocol when interacting with Cognito user pools bool true no
client_allowed_oauth_scopes List of allowed OAuth scopes (phone, email, openid, profile, and aws.cognito.signin.user.admin) list [] no
client_callback_urls List of allowed callback URLs for the identity providers list [] no
client_default_redirect_uri The default redirect URI. Must be in the list of callback URLs string "" no
client_explicit_auth_flows List of authentication flows (ADMIN_NO_SRP_AUTH, CUSTOM_AUTH_FLOW_ONLY, USER_PASSWORD_AUTH) list [] no
client_generate_secret Should an application secret be generated bool true no
client_logout_urls List of allowed logout URLs for the identity providers list [] no
client_name The name of the application client string n/a yes
client_prevent_user_existence_errors Choose which errors and responses are returned by Cognito APIs during authentication, account confirmation, and password recovery when the user does not exist in the user pool. When set to ENABLED and the user does not exist, authentication returns an error indicating either the username or password was incorrect, and account confirmation and password recovery return a response indicating a code was sent to a simulated destination. When set to LEGACY, those APIs will return a UserNotFoundException exception if the user does not exist in the user pool. string "" no
client_read_attributes List of user pool attributes the application client can read from list [] no
client_refresh_token_validity The time limit in days refresh tokens are valid for number 30 no
client_supported_identity_providers List of provider names for the identity providers that are supported on this client list [] no
client_write_attributes List of user pool attributes the application client can write to list [] no
clients A container with the clients definitions list [] no
device_configuration The configuration for the user pool's device tracking map {} no
device_configuration_challenge_required_on_new_device Indicates whether a challenge is required on a new device. Only applicable to a new device bool false no
device_configuration_device_only_remembered_on_user_prompt If true, a device is only remembered on user prompt bool false no
domain Cognito User Pool domain string n/a yes
domain_certificate_arn The ARN of an ISSUED ACM certificate in us-east-1 for a custom domain string n/a yes
email_configuration The Email Configuration map {} no
email_configuration_email_sending_account Instruct Cognito to either use its built-in functional or Amazon SES to send out emails. Allowed values: COGNITO_DEFAULT or DEVELOPER string "COGNITO_DEFAULT" no
email_configuration_reply_to_email_address The REPLY-TO email address string "" no
email_configuration_source_arn The ARN of the email source string "" no
email_verification_message A string representing the email verification message string n/a yes
email_verification_subject A string representing the email verification subject string n/a yes
lambda_config A container for the AWS Lambda triggers associated with the user pool map n/a yes
lambda_config_create_auth_challenge The ARN of the lambda creating an authentication challenge. string "" no
lambda_config_custom_message A custom Message AWS Lambda trigger. string "" no
lambda_config_define_auth_challenge Defines the authentication challenge. string "" no
lambda_config_post_authentication A post-authentication AWS Lambda trigger string "" no
lambda_config_post_confirmation A post-confirmation AWS Lambda trigger string "" no
lambda_config_pre_authentication A pre-authentication AWS Lambda trigger string "" no
lambda_config_pre_sign_up A pre-registration AWS Lambda trigger string "" no
lambda_config_pre_token_generation Allow to customize identity token claims before token generation string "" no
lambda_config_user_migration The user migration Lambda config type string "" no
lambda_config_verify_auth_challenge_response Verifies the authentication challenge response string "" no
mfa_configuration Set to enable multi-factor authentication. Must be one of the following values (ON, OFF, OPTIONAL) string "OFF" no
number_schemas A container with the number schema attributes of a user pool. Maximum of 50 attributes list [] no
password_policy A container for information about the user pool password policy
object({
minimum_length = number,
require_lowercase = bool,
require_lowercase = bool,
require_numbers = bool,
require_symbols = bool,
require_uppercase = bool,
temporary_password_validity_days = number
})
n/a yes
password_policy_minimum_length The minimum length of the password policy that you have set number 8 no
password_policy_require_lowercase Whether you have required users to use at least one lowercase letter in their password bool true no
password_policy_require_numbers Whether you have required users to use at least one number in their password bool true no
password_policy_require_symbols Whether you have required users to use at least one symbol in their password bool true no
password_policy_require_uppercase Whether you have required users to use at least one uppercase letter in their password bool true no
password_policy_temporary_password_validity_days The minimum length of the password policy that you have set number 7 no
resource_server_identifier An identifier for the resource server string n/a yes
resource_server_name A name for the resource server string n/a yes
resource_server_scope_description The scope description string n/a yes
resource_server_scope_name The scope name string n/a yes
resource_servers A container with the user_groups definitions list [] no
schemas A container with the schema attributes of a user pool. Maximum of 50 attributes list [] no
sms_authentication_message A string representing the SMS authentication message string n/a yes
sms_configuration The SMS Configuration map {} no
sms_configuration_external_id The external ID used in IAM role trust relationships string "" no
sms_configuration_sns_caller_arn The ARN of the Amazon SNS caller. This is usually the IAM role that you've given Cognito permission to assume string "" no
sms_verification_message A string representing the SMS verification message string n/a yes
software_token_mfa_configuration Configuration block for software token MFA (multifactor-auth). mfa_configuration must also be enabled for this to work map {} no
software_token_mfa_configuration_enabled If true, and if mfa_configuration is also enabled, multi-factor authentication by software TOTP generator will be enabled bool false no
string_schemas A container with the string schema attributes of a user pool. Maximum of 50 attributes list [] no
tags A mapping of tags to assign to the User Pool map(string) {} no
temporary_password_validity_days The user account expiration limit, in days, after which the account is no longer usable number 7 no
user_group_description The description of the user group string n/a yes
user_group_name The name of the user group string n/a yes
user_group_precedence The precedence of the user group number n/a yes
user_group_role_arn The ARN of the IAM role to be associated with the user group string n/a yes
user_groups A container with the user_groups definitions list [] no
user_pool_add_ons Configuration block for user pool add-ons to enable user pool advanced security mode features map {} no
user_pool_add_ons_advanced_security_mode The mode for advanced security, must be one of OFF, AUDIT or ENFORCED string n/a yes
user_pool_name The name of the user pool string n/a yes
username_attributes Specifies whether email addresses or phone numbers can be specified as usernames when a user signs up. Conflicts with alias_attributes list n/a yes
username_configuration The Username Configuration. Seting case_sesiteve specifies whether username case sensitivity will be applied for all users in the user pool through Cognito APIs map {} no
verification_message_template The verification message templates configuration map {} no
verification_message_template_default_email_option The default email option. Must be either CONFIRM_WITH_CODE or CONFIRM_WITH_LINK. Defaults to CONFIRM_WITH_CODE string n/a yes
verification_message_template_email_message_by_link The email message template for sending a confirmation link to the user, it must contain the {##Click Here##} placeholder string n/a yes
verification_message_template_email_subject_by_link The subject line for the email message template for sending a confirmation link to the user string n/a yes

Outputs

Name Description
arn The ARN of the user pool
client_ids The ids of the user pool clients
client_secrets The client secrets of the user pool clients
creation_date The date the user pool was created
domain_app_version The app version
domain_aws_account_id The AWS account ID for the user pool owner
domain_cloudfront_distribution_arn The ARN of the CloudFront distribution
domain_s3_bucket The S3 bucket where the static files for this domain are stored
endpoint The endpoint name of the user pool. Example format: cognito-idp.REGION.amazonaws.com/xxxx_yyyyy
id The id of the user pool
last_modified_date The date the user pool was last modified
resource_servers_scope_identifiers A list of all scopes configured in the format identifier/scope_name

Know issue

Removing all lambda triggers

If you define lambda triggers using the lambda_config block or any lambda_config_* variable and you want to remove all triggers, define the lambda_config block with an empty map {} and apply the plan. Then comment the lambda_config block or define it as null and apply the plan again.

This is needed because all paramters for the lambda_config block are optional and keeping all block attributes empty or null forces to create a lambda_config {} block very time a plan/apply is run.