An open API service indexing awesome lists of open source software.

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

Awesome Lists containing this project

README

          

![Module Structure](./static/cognito-banner.png)
## [terraform-aws-arc-cognito-userpool](https://github.com/sourcefuse/terraform-aws-arc-cognito-userpool)
![Terraform](https://img.shields.io/badge/terraform-%235835CC.svg?style=for-the-badge&logo=terraform&logoColor=white)
![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)

[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=sourcefuse_terraform-aws-arc-cognito-userpool&token=e28bfe630069bd645a51dee7e25cf3c7e522e9fd)](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