https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool
https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool
- Owner: sourcefuse
- License: apache-2.0
- Created: 2025-08-07T08:41:53.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-15T11:03:49.000Z (11 months ago)
- Last Synced: 2026-04-02T04:29:26.693Z (4 months ago)
- Language: HCL
- Size: 3.66 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README

## [terraform-aws-arc-cognito-userpool](https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool)


[](https://sonarcloud.io/summary/new_code?id=sourcefuse_terraform-aws-arc-cognito-userpool)
## Overview
SourceFuse AWS Reference Architecture (ARC) Terraform module for managing the cognito userpool module.
## Features
- **Complete Cognito User Pool Management**: Create and configure user pools with all available settings.
- **Security Best Practices**: Built-in security configurations following AWS recommendations.
- **Flexible Client Configuration**: Support for multiple app clients with different configurations.
- **Identity Provider Integration**: Support for SAML, OIDC, and social identity providers.
- **Advanced Security Features**: MFA, advanced security mode, adaptive authentication.
- **Lambda Triggers**: Support for all Cognito Lambda triggers.
- **Custom Domains**: Support for custom domains with SSL certificates.
- **User Pool Groups**: Role-based access control with user groups.
- **Resource Servers**: OAuth 2.0 resource server configuration.
## Usage
To see a full example, check out the [main.tf](https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool/blob/main/examples/basic-user-pool/main.tf) file in the example folder.
```hcl
module "arc-cognito-userpool" {
source = "sourcefuse/arc-cognito-userpool/aws"
version = "1.0.0"
environment = "dev"
project = "arc"
name = "auth"
region = "us-east-1"
# Example basic config
cognito_user_pool_name = "arc-demo-user-pool"
# Add further required variables
}
```
## Requirements
| Name | Version |
|------|---------|
| [terraform](#requirement\_terraform) | >= 1.6.0 |
| [aws](#requirement\_aws) | >= 5.0, < 7.0 |
## Providers
| Name | Version |
|------|---------|
| [aws](#provider\_aws) | 6.12.0 |
## Modules
| Name | Source | Version |
|------|--------|---------|
| [s3](#module\_s3) | sourcefuse/arc-s3/aws | 0.0.5 |
## Resources
| Name | Type |
|------|------|
| [aws_cloudwatch_log_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group) | resource |
| [aws_cloudwatch_log_resource_policy.cognito](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_resource_policy) | resource |
| [aws_cognito_identity_provider.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_identity_provider) | resource |
| [aws_cognito_log_delivery_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_log_delivery_configuration) | resource |
| [aws_cognito_resource_server.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_resource_server) | resource |
| [aws_cognito_risk_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_risk_configuration) | resource |
| [aws_cognito_user.users](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user) | resource |
| [aws_cognito_user_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_group) | resource |
| [aws_cognito_user_in_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_in_group) | resource |
| [aws_cognito_user_pool.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool) | resource |
| [aws_cognito_user_pool_client.hosted_ui](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool_client) | resource |
| [aws_cognito_user_pool_client.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool_client) | resource |
| [aws_cognito_user_pool_domain.hosted_ui](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool_domain) | resource |
| [aws_cognito_user_pool_domain.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool_domain) | resource |
| [aws_cognito_user_pool_ui_customization.hosted_ui](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cognito_user_pool_ui_customization) | resource |
| [aws_wafv2_web_acl_association.cognito_waf](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/wafv2_web_acl_association) | resource |
| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| [account\_recovery\_mechanisms](#input\_account\_recovery\_mechanisms) | List of account recovery mechanisms |
list(object({
name = string
priority = number
})) | [
{
"name": "verified_email",
"priority": 1
}
]
| no |
| [account\_takeover\_risk\_configuration](#input\_account\_takeover\_risk\_configuration) | n/a | object({
notify_configuration = object({
from = optional(string)
reply_to = optional(string)
source_arn = string
block_email = optional(object({
html_body = string
text_body = string
subject = string
}))
mfa_email = optional(object({
html_body = string
text_body = string
subject = string
}))
no_action_email = optional(object({
html_body = string
text_body = string
subject = string
}))
})
actions = object({
high_action = object({
event_action = string
notify = bool
})
medium_action = object({
event_action = string
notify = bool
})
low_action = object({
event_action = string
notify = bool
})
})
}) | `null` | no |
| [admin\_create\_user\_config](#input\_admin\_create\_user\_config) | Configuration for creating a new user profile | object({
allow_admin_create_user_only = optional(bool, false)
invite_message_template = optional(object({
email_message = optional(string)
email_subject = optional(string)
sms_message = optional(string)
}), {})
}) | `{}` | no |
| [alias\_attributes](#input\_alias\_attributes) | Attributes supported as an alias for this user pool. Valid values: phone\_number, email, or preferred\_username | `list(string)` | `[]` | no |
| [auto\_verified\_attributes](#input\_auto\_verified\_attributes) | Attributes to be auto-verified. Valid values: email, phone\_number | `list(string)` | `[]` | no |
| [cognito\_log\_delivery\_config](#input\_cognito\_log\_delivery\_config) | ============================================================================== VARIABLES - LOG STREAMING ============================================================================== | object({
event_source = string # e.g. "userAuthEvents" or "userNotification"
log_level = string # "ERROR" or "INFO"
log_destination_type = string # "cloudwatch", "s3", "firehose"
# Optional overrides
log_group_name = optional(string) # for CW logs
s3_bucket_name = optional(string) # for S3
firehose_stream_arn = optional(string) # for Firehose
}) | `null` | no |
| [compromised\_credentials\_risk\_configuration](#input\_compromised\_credentials\_risk\_configuration) | n/a | object({
event_filter = optional(list(string))
actions = object({
event_action = string
})
}) | `null` | no |
| [create\_resource\_servers](#input\_create\_resource\_servers) | Whether to create resource servers | `bool` | `false` | no |
| [create\_user\_pool\_clients](#input\_create\_user\_pool\_clients) | Whether to create user pool clients | `bool` | `true` | no |
| [create\_user\_pool\_domain](#input\_create\_user\_pool\_domain) | Whether to create user pool domain | `bool` | `false` | no |
| [create\_user\_pool\_groups](#input\_create\_user\_pool\_groups) | Whether to create user pool groups | `bool` | `false` | no |
| [create\_user\_pool\_users](#input\_create\_user\_pool\_users) | Whether to create user pool users | `bool` | `false` | no |
| [deletion\_protection](#input\_deletion\_protection) | When active, DeletionProtection prevents accidental deletion of your user pool | `string` | `"INACTIVE"` | no |
| [device\_configuration](#input\_device\_configuration) | Configuration for the user pool's device tracking | object({
challenge_required_on_new_device = optional(bool, false)
device_only_remembered_on_user_prompt = optional(bool, false)
}) | `null` | no |
| [email\_configuration](#input\_email\_configuration) | Configuration for email settings | object({
configuration_set = optional(string)
email_sending_account = optional(string, "COGNITO_DEFAULT")
from_email_address = optional(string)
reply_to_email_address = optional(string)
source_arn = optional(string)
}) | `{}` | no |
| [email\_verification\_message](#input\_email\_verification\_message) | String representing the email verification message | `string` | `null` | no |
| [email\_verification\_subject](#input\_email\_verification\_subject) | String representing the email verification subject | `string` | `null` | no |
| [hosted\_ui\_config](#input\_hosted\_ui\_config) | Cognito Hosted UI configuration | object({
name = string
domain = string
certificate_arn = optional(string)
callback_urls = list(string)
logout_urls = list(string)
default_redirect_uri = optional(string)
allowed_oauth_flows = list(string)
allowed_oauth_flows_user_pool_client = optional(bool, true)
allowed_oauth_scopes = list(string)
supported_identity_providers = list(string)
generate_secret = optional(bool, false)
css_file = optional(string)
image_file = optional(string)
}) | `null` | no |
| [identity\_providers\_config](#input\_identity\_providers\_config) | Configuration for optional identity providers | object({
google = optional(object({
enabled = optional(bool, false)
client_id = optional(string)
client_secret = optional(string)
scopes = optional(list(string), ["openid", "email", "profile"])
attribute_mapping = optional(map(string), {})
authorize_url = optional(string, "https://accounts.google.com/o/oauth2/v2/auth")
token_url = optional(string, "https://www.googleapis.com/oauth2/v4/token")
attributes_url = optional(string, "https://people.googleapis.com/v1/people/me?personFields=")
attributes_url_add_attributes = optional(string, "true")
oidc_issuer = optional(string, "https://accounts.google.com")
token_request_method = optional(string, "POST")
}), {})
facebook = optional(object({
enabled = optional(bool, false)
app_id = optional(string)
app_secret = optional(string)
scopes = optional(list(string), ["public_profile", "email"])
attribute_mapping = optional(map(string), {})
authorize_url = optional(string, "https://www.facebook.com/v17.0/dialog/oauth")
token_url = optional(string, "https://graph.facebook.com/v17.0/oauth/access_token")
attributes_url = optional(string, "https://graph.facebook.com/v17.0/me?fields=")
attributes_url_add_attributes = optional(string, "true")
token_request_method = optional(string, "GET")
}), {})
apple = optional(object({
enabled = optional(bool, false)
services_id = optional(string)
team_id = optional(string)
key_id = optional(string)
private_key = optional(string)
scopes = optional(list(string), ["name", "email"])
attribute_mapping = optional(map(string), {})
}), {})
amazon = optional(object({
enabled = optional(bool, false)
client_id = optional(string)
client_secret = optional(string)
scopes = optional(list(string), ["profile"])
attribute_mapping = optional(map(string), {})
}), {})
saml = optional(object({
enabled = optional(bool, false)
provider_name = optional(string)
metadata_url = optional(string)
attribute_mapping = optional(map(string), {})
idp_identifiers = optional(list(string), [])
}), {})
oidc = optional(object({
enabled = optional(bool, false)
provider_name = optional(string)
client_id = optional(string)
client_secret = optional(string)
issuer_url = optional(string)
scopes = optional(list(string), ["openid", "email", "profile"])
attribute_mapping = optional(map(string), {})
}), {})
}) | `{}` | no |
| [lambda\_config](#input\_lambda\_config) | Configuration for AWS Lambda triggers associated with the user pool | object({
create_auth_challenge = optional(string)
custom_message = optional(string)
define_auth_challenge = optional(string)
post_authentication = optional(string)
post_confirmation = optional(string)
pre_authentication = optional(string)
pre_sign_up = optional(string)
pre_token_generation = optional(string)
user_migration = optional(string)
verify_auth_challenge_response = optional(string)
kms_key_id = optional(string)
custom_email_sender = optional(object({
lambda_arn = string
lambda_version = string
}))
custom_sms_sender = optional(object({
lambda_arn = string
lambda_version = string
}))
pre_token_generation_config = optional(object({
lambda_arn = string
lambda_version = string
}))
}) | `null` | no |
| [mfa\_configuration](#input\_mfa\_configuration) | Multi-Factor Authentication (MFA) configuration for the User Pool. Set to null to omit. | `string` | `null` | no |
| [name](#input\_name) | Name of the Cognito User Pool | `string` | n/a | yes |
| [password\_policy](#input\_password\_policy) | Configuration for the user pool password policy | object({
minimum_length = optional(number, 8)
require_lowercase = optional(bool, true)
require_numbers = optional(bool, true)
require_symbols = optional(bool, true)
require_uppercase = optional(bool, true)
temporary_password_validity_days = optional(number, 7)
password_history_size = optional(number, 0)
}) | `{}` | no |
| [resource\_servers](#input\_resource\_servers) | List of resource servers to create | list(object({
identifier = string
name = string
scope = optional(list(object({
scope_name = string
scope_description = string
})), [])
})) | `[]` | no |
| [risk\_exception\_configuration](#input\_risk\_exception\_configuration) | n/a | object({
blocked_ip_range_list = optional(list(string))
skipped_ip_range_list = optional(list(string))
}) | `null` | no |
| [schema](#input\_schema) | Configuration for the schema attributes of a user pool | list(object({
attribute_data_type = string
developer_only_attribute = optional(bool, false)
mutable = optional(bool, true)
name = string
required = optional(bool, false)
number_attribute_constraints = optional(object({
max_value = optional(string)
min_value = optional(string)
}))
string_attribute_constraints = optional(object({
max_length = optional(string)
min_length = optional(string)
}))
})) | `[]` | no |
| [sms\_authentication\_message](#input\_sms\_authentication\_message) | String representing the SMS authentication message | `string` | `null` | no |
| [sms\_configuration](#input\_sms\_configuration) | Configuration for SMS settings | object({
external_id = string
sns_caller_arn = string
sns_region = optional(string)
}) | `null` | no |
| [sms\_verification\_message](#input\_sms\_verification\_message) | String representing the SMS verification message | `string` | `null` | no |
| [software\_token\_mfa\_configuration](#input\_software\_token\_mfa\_configuration) | Configuration for software token Multi-Factor Authentication (MFA) settings. Set to null to omit. | object({
enabled = bool
}) | `null` | no |
| [tags](#input\_tags) | A map of tags to assign to the resources | `map(string)` | `{}` | no |
| [user\_attribute\_update\_settings](#input\_user\_attribute\_update\_settings) | Configuration for user attribute update settings | object({
attributes_require_verification_before_update = list(string)
}) | `null` | no |
| [user\_group\_memberships](#input\_user\_group\_memberships) | List of user-to-group memberships | list(object({
user = string
group = string
})) | `[]` | no |
| [user\_pool\_add\_ons](#input\_user\_pool\_add\_ons) | Advanced security configuration for Cognito User Pool.
- advanced\_security\_mode: OFF \| AUDIT \| ENFORCED
- advanced\_security\_additional\_flows: (optional) block for custom flows
- custom\_auth\_mode: e.g. "AUDIT" or "ENFORCED" | object({
advanced_security_mode = string
advanced_security_additional_flows = optional(object({
custom_auth_mode = string
}))
}) | `null` | no |
| [user\_pool\_clients](#input\_user\_pool\_clients) | List of user pool clients to create | list(object({
name = string
access_token_validity = optional(number, 60)
id_token_validity = optional(number, 60)
refresh_token_validity = optional(number, 30)
token_validity_units = optional(object({
access_token = optional(string, "minutes")
id_token = optional(string, "minutes")
refresh_token = optional(string, "days")
}), {})
allowed_oauth_flows = optional(list(string), [])
allowed_oauth_flows_user_pool_client = optional(bool, false)
allowed_oauth_scopes = optional(list(string), [])
callback_urls = optional(list(string), [])
default_redirect_uri = optional(string)
explicit_auth_flows = optional(list(string), ["ALLOW_USER_SRP_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"])
generate_secret = optional(bool, false)
logout_urls = optional(list(string), [])
prevent_user_existence_errors = optional(string, "ENABLED")
read_attributes = optional(list(string), [])
supported_identity_providers = optional(list(string), ["GOOGLE"])
write_attributes = optional(list(string), [])
enable_token_revocation = optional(bool, true)
enable_propagate_additional_user_context_data = optional(bool, false)
auth_session_validity = optional(number, 3)
})) | `[]` | no |
| [user\_pool\_domain](#input\_user\_pool\_domain) | Configuration for user pool domain | object({
domain = string
certificate_arn = optional(string)
}) | `null` | no |
| [user\_pool\_groups](#input\_user\_pool\_groups) | List of user pool groups to create | list(object({
name = string
description = optional(string)
precedence = optional(number)
role_arn = optional(string)
})) | `[]` | no |
| [user\_pool\_tier](#input\_user\_pool\_tier) | The user pool feature plan, or tier | `string` | `"ESSENTIALS"` | no |
| [user\_pool\_users](#input\_user\_pool\_users) | List of Cognito users to create | list(object({
username = string
email = string
password = string
})) | `[]` | no |
| [username\_attributes](#input\_username\_attributes) | Whether email addresses or phone numbers can be specified as usernames when a user signs up | `list(string)` | `[]` | no |
| [username\_configuration](#input\_username\_configuration) | Configuration for username settings | object({
case_sensitive = optional(bool, false)
}) | `{}` | no |
| [verification\_message\_template](#input\_verification\_message\_template) | Configuration for verification message templates | object({
default_email_option = optional(string, "CONFIRM_WITH_CODE")
email_message = optional(string)
email_message_by_link = optional(string)
email_subject = optional(string)
email_subject_by_link = optional(string)
sms_message = optional(string)
}) | `null` | no |
| [web\_acl\_arn](#input\_web\_acl\_arn) | Optional WAF Web ACL ARN to associate with Cognito User Pool. Null = inactive | `string` | `null` | no |
| [web\_authn\_configuration](#input\_web\_authn\_configuration) | Configuration for web authn (passkey) settings | object({
relying_party_id = optional(string)
user_verification = optional(string, "preferred")
}) | `null` | no |
## Outputs
| Name | Description |
|------|-------------|
| [identity\_provider\_names](#output\_identity\_provider\_names) | The names of the Cognito Identity Providers |
| [identity\_providers](#output\_identity\_providers) | Map of identity provider details |
| [resource\_server\_identifiers](#output\_resource\_server\_identifiers) | The identifiers of the Cognito Resource Servers |
| [resource\_server\_names](#output\_resource\_server\_names) | The names of the Cognito Resource Servers |
| [resource\_servers](#output\_resource\_servers) | Map of resource server details |
| [summary](#output\_summary) | Summary of all created resources |
| [user\_pool\_arn](#output\_user\_pool\_arn) | The ARN of the Cognito User Pool |
| [user\_pool\_client\_ids](#output\_user\_pool\_client\_ids) | The IDs of the Cognito User Pool Clients |
| [user\_pool\_client\_names](#output\_user\_pool\_client\_names) | The names of the Cognito User Pool Clients |
| [user\_pool\_client\_secrets](#output\_user\_pool\_client\_secrets) | The client secrets of the Cognito User Pool Clients (sensitive) |
| [user\_pool\_clients](#output\_user\_pool\_clients) | Map of user pool client details |
| [user\_pool\_creation\_date](#output\_user\_pool\_creation\_date) | The date the Cognito User Pool was created |
| [user\_pool\_custom\_domain](#output\_user\_pool\_custom\_domain) | The custom domain name for the user pool |
| [user\_pool\_domain](#output\_user\_pool\_domain) | The domain prefix if the user pool has a domain associated with it |
| [user\_pool\_domain\_aws\_account\_id](#output\_user\_pool\_domain\_aws\_account\_id) | The AWS account ID for the user pool domain |
| [user\_pool\_domain\_cloudfront\_distribution\_arn](#output\_user\_pool\_domain\_cloudfront\_distribution\_arn) | The ARN of the CloudFront distribution for the domain |
| [user\_pool\_domain\_name](#output\_user\_pool\_domain\_name) | The domain name of the Cognito User Pool Domain |
| [user\_pool\_domain\_s3\_bucket](#output\_user\_pool\_domain\_s3\_bucket) | The S3 bucket where the static files for this domain are stored |
| [user\_pool\_domain\_version](#output\_user\_pool\_domain\_version) | The app version for the domain |
| [user\_pool\_endpoint](#output\_user\_pool\_endpoint) | The endpoint name of the Cognito User Pool |
| [user\_pool\_estimated\_number\_of\_users](#output\_user\_pool\_estimated\_number\_of\_users) | A number estimating the size of the user pool |
| [user\_pool\_group\_names](#output\_user\_pool\_group\_names) | The names of the Cognito User Pool Groups |
| [user\_pool\_groups](#output\_user\_pool\_groups) | Map of user pool group details |
| [user\_pool\_hosted\_ui\_url](#output\_user\_pool\_hosted\_ui\_url) | The URL of the hosted UI for the user pool (if domain is configured) |
| [user\_pool\_id](#output\_user\_pool\_id) | The ID of the Cognito User Pool |
| [user\_pool\_issuer](#output\_user\_pool\_issuer) | The issuer URL for the user pool |
| [user\_pool\_jwks\_uri](#output\_user\_pool\_jwks\_uri) | The JSON Web Key Set (JWKS) URI for the user pool |
| [user\_pool\_last\_modified\_date](#output\_user\_pool\_last\_modified\_date) | The date the Cognito User Pool was last modified |
| [user\_pool\_name](#output\_user\_pool\_name) | The name of the Cognito User Pool |
## Development
### Prerequisites
- [terraform](https://learn.hashicorp.com/terraform/getting-started/install#installing-terraform)
- [terraform-docs](https://github.com/segmentio/terraform-docs)
- [pre-commit](https://pre-commit.com/#install)
- [golang](https://golang.org/doc/install#install)
- [golint](https://github.com/golang/lint#installation)
### Configurations
- Configure pre-commit hooks
```sh
pre-commit install
```
### Versioning
while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch
For Example
```sh
git commit -m "your commit message #major"
```
By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly
## Authors
This project is authored by:
- SourceFuse ARC Team