Skip to content

Index

Module Structure

terraform-aws-arc-cognito-userpool

Terraform GitHub Actions

Quality gate

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 file in the example folder.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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 >= 1.6.0
aws >= 5.0, < 7.0

Providers

Name Version
aws 6.12.0

Modules

Name Source Version
s3 sourcefuse/arc-s3/aws 0.0.5

Resources

Name Type
aws_cloudwatch_log_group.this resource
aws_cloudwatch_log_resource_policy.cognito resource
aws_cognito_identity_provider.this resource
aws_cognito_log_delivery_configuration.this resource
aws_cognito_resource_server.this resource
aws_cognito_risk_configuration.this resource
aws_cognito_user.users resource
aws_cognito_user_group.this resource
aws_cognito_user_in_group.this resource
aws_cognito_user_pool.this resource
aws_cognito_user_pool_client.hosted_ui resource
aws_cognito_user_pool_client.this resource
aws_cognito_user_pool_domain.hosted_ui resource
aws_cognito_user_pool_domain.this resource
aws_cognito_user_pool_ui_customization.hosted_ui resource
aws_wafv2_web_acl_association.cognito_waf resource
aws_region.current data source

Inputs

Name Description Type Default Required
account_recovery_mechanisms List of account recovery mechanisms 
list(object({
    name     = string
    priority = number
  }))
 
[
  {
    "name": "verified_email",
    "priority": 1
  }
]
 no
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 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 Attributes supported as an alias for this user pool. Valid values: phone_number, email, or preferred_username list(string) [] no
auto_verified_attributes Attributes to be auto-verified. Valid values: email, phone_number list(string) [] no
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 n/a 
object({
    event_filter = optional(list(string))
    actions = object({
      event_action = string
    })
  })
 null no
create_resource_servers Whether to create resource servers bool false no
create_user_pool_clients Whether to create user pool clients bool true no
create_user_pool_domain Whether to create user pool domain bool false no
create_user_pool_groups Whether to create user pool groups bool false no
create_user_pool_users Whether to create user pool users bool false no
deletion_protection When active, DeletionProtection prevents accidental deletion of your user pool string "INACTIVE" no
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 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 String representing the email verification message string null no
email_verification_subject String representing the email verification subject string null no
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 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 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 Multi-Factor Authentication (MFA) configuration for the User Pool. Set to null to omit. string null no
name Name of the Cognito User Pool string n/a yes
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 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 n/a 
object({
    blocked_ip_range_list = optional(list(string))
    skipped_ip_range_list = optional(list(string))
  })
 null no
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 String representing the SMS authentication message string null no
sms_configuration Configuration for SMS settings 
object({
    external_id    = string
    sns_caller_arn = string
    sns_region     = optional(string)
  })
 null no
sms_verification_message String representing the SMS verification message string null no
software_token_mfa_configuration Configuration for software token Multi-Factor Authentication (MFA) settings. Set to null to omit. 
object({
    enabled = bool
  })
 null no
tags A map of tags to assign to the resources map(string) {} no
user_attribute_update_settings Configuration for user attribute update settings 
object({
    attributes_require_verification_before_update = list(string)
  })
 null no
user_group_memberships List of user-to-group memberships 
list(object({
    user  = string
    group = string
  }))
 [] no
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 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 Configuration for user pool domain 
object({
    domain          = string
    certificate_arn = optional(string)
  })
 null no
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 The user pool feature plan, or tier string "ESSENTIALS" no
user_pool_users List of Cognito users to create 
list(object({
    username = string
    email    = string
    password = string
  }))
 [] no
username_attributes Whether email addresses or phone numbers can be specified as usernames when a user signs up list(string) [] no
username_configuration Configuration for username settings 
object({
    case_sensitive = optional(bool, false)
  })
 {} no
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 Optional WAF Web ACL ARN to associate with Cognito User Pool. Null = inactive string null no
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 The names of the Cognito Identity Providers
identity_providers Map of identity provider details
resource_server_identifiers The identifiers of the Cognito Resource Servers
resource_server_names The names of the Cognito Resource Servers
resource_servers Map of resource server details
summary Summary of all created resources
user_pool_arn The ARN of the Cognito User Pool
user_pool_client_ids The IDs of the Cognito User Pool Clients
user_pool_client_names The names of the Cognito User Pool Clients
user_pool_client_secrets The client secrets of the Cognito User Pool Clients (sensitive)
user_pool_clients Map of user pool client details
user_pool_creation_date The date the Cognito User Pool was created
user_pool_custom_domain The custom domain name for the user pool
user_pool_domain The domain prefix if the user pool has a domain associated with it
user_pool_domain_aws_account_id The AWS account ID for the user pool domain
user_pool_domain_cloudfront_distribution_arn The ARN of the CloudFront distribution for the domain
user_pool_domain_name The domain name of the Cognito User Pool Domain
user_pool_domain_s3_bucket The S3 bucket where the static files for this domain are stored
user_pool_domain_version The app version for the domain
user_pool_endpoint The endpoint name of the Cognito User Pool
user_pool_estimated_number_of_users A number estimating the size of the user pool
user_pool_group_names The names of the Cognito User Pool Groups
user_pool_groups Map of user pool group details
user_pool_hosted_ui_url The URL of the hosted UI for the user pool (if domain is configured)
user_pool_id The ID of the Cognito User Pool
user_pool_issuer The issuer URL for the user pool
user_pool_jwks_uri The JSON Web Key Set (JWKS) URI for the user pool
user_pool_last_modified_date The date the Cognito User Pool was last modified
user_pool_name The name of the Cognito User Pool

Development

Prerequisites

Configurations

  • Configure pre-commit hooks 
    1
    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

1
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