Terraform module for Amazon Cognito User Pools
I share here another Terraform module that I just published as open source, which allows you to create Amazon Cognito User Pools with its attributes and resouces such as app clients, domain y resource server.
You can check the module terraform-aws-cognito-user-pool at the Terraform Registry or clone it from Github.
If you want to take a sneak of the module, I also left the README in this post:
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 = "../modules/terraform-aws-cognito-user-pool"
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 = "../modules/terraform-aws-cognito-user-pool"
user_pool_name = "mypool"
alias_attributes = ["email", "phone_number"]
auto_verified_attributes = ["email"]
admin_create_user_config = {
unused_account_validity_days = 9
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 = "productionq q | `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_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 | ```hcl object({ minimum_length = number, require_lowercase = bool, require_lowercase = bool, require_numbers = bool, require_symbols = bool, require_uppercase = bool }) ``` | 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 |
| 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 |
| 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 |
| 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 |
| 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.
Leave a Comment