### Manual Asset Creation with ImageMagick

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/with_branding/assets/README.md

Manually create placeholder assets using ImageMagick commands. The `convert` command requires ImageMagick to be installed. These examples create a colored rectangle as a logo, a gradient background, and a simple favicon.

```bash
# Create a simple colored rectangle as logo
convert -size 200x60 xc:blue logo-light.png
convert -size 200x60 xc:white logo-dark.png
```

```bash
# Create a gradient background
convert -size 1920x1080 gradient:blue-lightblue background.jpg
```

```bash
# Create a simple favicon
convert -size 32x32 xc:blue favicon.ico
```

--------------------------------

### Request Cognito Resource Documentation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for requesting advanced security feature documentation from Claude.

```text
@claude I need to add support for Cognito advanced security features. Can you look up the latest aws_cognito_user_pool advanced_security_mode documentation and show me how to implement this feature?
```

--------------------------------

### Request Security Enhancement Research

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for researching and implementing enhanced MFA configurations.

```text
@claude Research the latest AWS Cognito security best practices and help me implement enhanced MFA configurations in this module.
```

--------------------------------

### Request AI Implementation Validation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for validating user pool client implementations against security best practices.

```text
@claude Use the terraform-cognito and terraform-security agents to validate my implementation of user pool clients with identity providers. Check for security issues and AWS best practices.
```

--------------------------------

### Manual State Migration for Clients with Names

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Example Terraform state mv commands for migrating user pool clients that have names defined in the configuration.

```bash
terraform state mv 'aws_cognito_user_pool_client.client[0]' 'aws_cognito_user_pool_client.client["web-app_0"]'
terraform state mv 'aws_cognito_user_pool_client.client[1]' 'aws_cognito_user_pool_client.client["mobile-app_1"]'
```

--------------------------------

### Manual State Migration for Mixed Client Configurations

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Example Terraform state mv commands for migrating user pool clients in a configuration that includes both named and unnamed clients.

```bash
terraform state mv 'aws_cognito_user_pool_client.client[0]' 'aws_cognito_user_pool_client.client["web-app_0"]'
terraform state mv 'aws_cognito_user_pool_client.client[1]' 'aws_cognito_user_pool_client.client["client_1"]'
```

--------------------------------

### Identify UI customization state addresses

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Example of legacy and current state addresses for UI customization resources.

```hcl
module.<your_module_name>.aws_cognito_user_pool_ui_customization.ui_customization["client-0"]
```

```hcl
module.<your_module_name>.aws_cognito_user_pool_ui_customization.ui_customization["client_0"]
```

--------------------------------

### Request AI validation for modifications

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for verifying backward compatibility and security implications after modifying password policy configurations.

```text
@claude I've modified the password policy configuration. Please use the
cognito-migration agent to verify backward compatibility and the
terraform-security agent to validate the security implications.
```

--------------------------------

### Provider Version Error

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Example of the error message displayed when the AWS provider version is insufficient.

```text
Error: Module requires aws provider version >= 6.12.0
```

--------------------------------

### Request AI Validation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Example prompt for invoking specialized subagents to review Terraform configurations.

```text
@claude Please use the terraform-cognito and terraform-security agents to validate
this implementation. Check for AWS best practices, security concerns, and proper
integration with existing module patterns.
```

--------------------------------

### Request AI validation for security-critical changes

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for performing a comprehensive security analysis on updated MFA configurations.

```text
@claude Use the terraform-security agent to perform a comprehensive security
analysis of the updated MFA configuration. Check for any security weaknesses
or misconfigurations.
```

--------------------------------

### Example of Perpetual Diff Output

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

This block illustrates the typical Terraform plan output showing a perpetual diff for schema attributes.

```text
- schema {
  - attribute_data_type      = "String" -> null
  - developer_only_attribute = false -> null
  - mutable                  = true -> null
  - name                     = "roles" -> null
  - required                 = false -> null
  - string_attribute_constraints {}
}
+ schema {
  + attribute_data_type      = "String"
  + developer_only_attribute = false
  + mutable                  = true
  + name                     = "roles"
  + required                 = false
}
```

--------------------------------

### Request AI validation for new features

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Example prompt for requesting a review of new advanced security mode features using specific agents.

```text
@claude Please use the terraform-cognito and terraform-security agents to review
the new advanced security mode feature I just implemented. Validate the
implementation follows AWS best practices and check for any security concerns.
```

--------------------------------

### Manual State Migration for Clients without Names

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Example Terraform state mv commands for migrating user pool clients where no specific name is provided in the configuration.

```bash
terraform state mv 'aws_cognito_user_pool_client.client[0]' 'aws_cognito_user_pool_client.client["client_0"]'
terraform state mv 'aws_cognito_user_pool_client.client[1]' 'aws_cognito_user_pool_client.client["client_1"]'
```

--------------------------------

### Configure AWS Cognito User Pool with Custom Schemas

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/complete/README.md

This example configures a complete AWS Cognito User Pool with custom attributes, MFA, email/SMS settings, password policies, and Lambda triggers. Ensure `ignore_schema_changes = true` is set when using custom schemas to prevent perpetual diffs and API errors.

```hcl
module "aws_cognito_user_pool_complete_example" {

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

  user_pool_name             = "mypool_complete"
  alias_attributes           = ["email", "phone_number"]
  auto_verified_attributes   = ["email"]
  sms_authentication_message = "Your username is {username} and temporary password is {####}."
  sms_verification_message   = "This is the verification message {####}."

  deletion_protection = "ACTIVE"

  # IMPORTANT: Enable schema ignore changes to prevent perpetual diffs with custom schemas
  # This is ESSENTIAL for this example since it uses custom schemas (schemas, string_schemas, number_schemas)
  # Without this, Terraform will attempt to recreate schemas on every plan, causing AWS API errors
  ignore_schema_changes = true

  mfa_configuration = "OPTIONAL"
  software_token_mfa_configuration = {
    enabled = true
  }

  admin_create_user_config = {
    email_message = "Dear {username}, your verification code is {####}."
    email_subject = "Here, your verification code baby"
    sms_message   = "Your username is {username} and temporary password is {####}."
  }

  device_configuration = {
    challenge_required_on_new_device      = true
    device_only_remembered_on_user_prompt = true
  }

  email_configuration = {
    email_sending_account  = "DEVELOPER"
    reply_to_email_address = "email@mydomain.com"
    source_arn             = "arn:aws:ses:us-east-1:123456789012:identity/myemail@mydomain.com"
    from_email_address     = "noreply@mydomain.com"
    configuration_set      = "my-configuration-set"
  }

  lambda_config = {
    create_auth_challenge          = "arn:aws:lambda:us-east-1:123456789012:function:create_auth_challenge"
    custom_message                 = "arn:aws:lambda:us-east-1:123456789012:function:custom_message"
    define_auth_challenge          = "arn:aws:lambda:us-east-1:123456789012:function:define_auth_challenge"
    post_authentication            = "arn:aws:lambda:us-east-1:123456789012:function:post_authentication"
    post_confirmation              = "arn:aws:lambda:us-east-1:123456789012:function:post_confirmation"
    pre_authentication             = "arn:aws:lambda:us-east-1:123456789012:function:pre_authentication"
    pre_sign_up                    = "arn:aws:lambda:us-east-1:123456789012:function:pre_sign_up"
    pre_token_generation           = "arn:aws:lambda:us-east-1:123456789012:function:pre_token_generation"
    user_migration                 = "arn:aws:lambda:us-east-1:123456789012:function:user_migration"
    verify_auth_challenge_response = "arn:aws:lambda:us-east-1:123456789012:function:verify_auth_challenge_response"
  }

  password_policy = {
    minimum_length                   = 10
    require_lowercase                = false
    require_numbers                  = true
    require_symbols                  = true
    require_uppercase                = true
    temporary_password_validity_days = 120

  }

  user_pool_add_ons = {
    advanced_security_mode = "ENFORCED"
  }

  verification_message_template = {
    default_email_option = "CONFIRM_WITH_CODE"
  }

  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
      }
    },
    {
      attribute_data_type      = "String"
      developer_only_attribute = false
      mutable                  = false
      name                     = "gender"
      required                 = true

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

  number_schemas = [
    {
      attribute_data_type      = "Number"
      developer_only_attribute = true
      mutable                  = true
      name                     = "mynumber1"
      required                 = false

      number_attribute_constraints = {
        min_value = 2
        max_value = 6
      }
    },
    {
      attribute_data_type      = "Number"
      developer_only_attribute = true
      mutable                  = true

```

--------------------------------

### Execute Migration Commands

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Run these commands to initialize the new provider, plan, and apply the changes.

```bash
# 1. Download the new provider version
terraform init -upgrade

# 2. Review the changes (should be minimal/none for most users)
terraform plan

# 3. Apply the changes
terraform apply
```

--------------------------------

### Import native branding resource

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Use this command if state move is not possible, providing the user pool ID and branding ID.

```bash
terraform import \
  'module.<your_module_name>.aws_cognito_managed_login_branding.branding["main"]' \
  'us-east-1_AbCdEfGhI,<managed-login-branding-id>'
```

--------------------------------

### Generate Sample Assets Script

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/with_branding/assets/README.md

Run this bash script to quickly generate all required sample assets for testing purposes. Customize these with your actual brand assets before production use.

```bash
# Run the asset generation script
./generate-sample-assets.sh
```

--------------------------------

### Terraform Commands for Deployment

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/refresh_token_rotation/README.md

Standard Terraform commands to initialize, plan, and apply the configuration.

```bash
terraform init
terraform plan
terraform apply
```

--------------------------------

### Run Migration Helper Script

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Executes the bash script to automate the migration of user pool clients from count-based to for_each-based implementations.

```bash
chmod +x migrate-clients.sh
./migrate-clients.sh
```

--------------------------------

### Configure Context7 MCP Server

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Local configuration for the Context7 MCP server to access general library and framework documentation.

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
```

--------------------------------

### User Pool Client Key Generation Pattern

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Illustrates the key generation pattern used in the for_each implementation for user pool clients, incorporating client names and an index.

```hcl
"${lookup(client, "name", "client")}_${idx}" => client
```

--------------------------------

### Structure locals for clarity

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Organize locals to handle resource creation conditions, data processing, and validation helpers.

```hcl
locals {
  # Resource creation conditions
  should_create_pool   = var.enabled && var.user_pool_name != null
  should_create_domain = local.should_create_pool && var.domain != null

  # Data processing
  clients = concat(local.default_client, var.clients)

  # Validation helpers
  mfa_requirements_met = var.mfa_configuration != null && var.software_token_mfa_configuration != null
}
```

--------------------------------

### Use for_each for resource creation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Prefer for_each over count for resource creation to improve maintainability and resource tracking.

```hcl
# Preferred: Using for_each
resource "aws_cognito_user_pool_client" "this" {
  for_each = var.enabled ? var.clients : {}

  name         = each.value.name
  user_pool_id = aws_cognito_user_pool.pool[0].id
  # ...
}

# Avoid: Using count when for_each is more appropriate
resource "aws_cognito_user_pool_client" "this" {
  count = var.enabled ? length(var.clients) : 0
  # ...
}
```

--------------------------------

### Handle Multi-Selection Input Formats

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Flattens various input formats for client configurations into a single list to support both legacy and new structures.

```hcl
client_configurations = flatten([
  var.client_configurations,
  [for client in try(tolist(var.clients), []) : try(client.configuration, [])],
  [for k, client in try(tomap(var.clients), {}) : try(client.configuration, [])],
  [for client in var.user_pool_clients : try(client.configuration, [])],
  [for pool in var.pools : flatten([for client in try(pool.clients, []) : try(client.configuration, [])])]
])
```

--------------------------------

### Enable Schema Fix for Existing Deployments

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Configuration and CLI commands to migrate an existing deployment to the schema-ignore variant.

```hcl
# Enable the fix in your configuration
ignore_schema_changes = true
```

```bash
# Plan to see the changes
terraform plan

# Apply - this will create the new resource variant
terraform apply

# Import existing state to the new resource
terraform state mv aws_cognito_user_pool.pool[0] aws_cognito_user_pool.pool_with_schema_ignore[0]
```

--------------------------------

### Create a simple Cognito User Pool

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Deploys a basic Cognito User Pool with default settings and schema change ignoring enabled.

```hcl
module "aws_cognito_user_pool_simple" {
  source  = "lgallard/cognito-user-pool/aws"

  user_pool_name = "mypool"

  # Recommended: Enable schema ignore changes for new deployments
  # This prevents perpetual diffs if you plan to use custom schemas
  ignore_schema_changes = true

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

--------------------------------

### Create Multiple Resources with for_each

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Iterates over a list of clients to create multiple Cognito user pool client resources using a unique key.

```hcl
resource "aws_cognito_user_pool_client" "this" {
  for_each = {
    for idx, client in var.user_pool_clients :
    "${client.name}_${idx}" => client
  }

  user_pool_id = aws_cognito_user_pool.pool[0].id
  name         = each.value.name

  dynamic "explicit_auth_flows" {
    for_each = each.value.explicit_auth_flows
    content {
      # auth flow configuration
    }
  }
}
```

--------------------------------

### Define sign_in_policy object

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Configuration block for sign-in policy. Allows configuring choice-based first authentication factors such as PASSWORD, EMAIL_OTP, SMS_OTP, and WEB_AUTHN.

```hcl
object({
    allowed_first_auth_factors = list(string)
  })
```

--------------------------------

### AI Agent Validation Workflow Prompts

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Use these prompts to interact with AI agents for code review, security analysis, and documentation validation during the development lifecycle.

```text
# After implementing a new feature
@claude I've added support for custom email sender configuration. Please:
1. Use terraform-cognito agent to review the implementation
2. Use terraform-security agent to check for security issues
3. Use module-documentation agent to validate the examples
4. Provide specific feedback on any concerns or improvements needed

# After making security changes
@claude I've updated the account takeover prevention settings. Use the
terraform-security agent to perform a thorough security analysis and
verify this follows AWS security best practices.

# Before releasing changes
@claude Please use the cognito-migration and module-documentation agents
to verify backward compatibility and ensure documentation is complete
for the changes in this branch.
```

--------------------------------

### Export Cognito User Pool Client Configuration

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

AWS CLI command to describe and export the settings of a specific Cognito user pool client, useful for backup before manual recreation.

```bash
aws cognito-idp describe-user-pool-client --user-pool-id <pool_id> --client-id <client_id>
```

--------------------------------

### List Current Cognito User Pool Clients in State

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Command to list all current aws_cognito_user_pool_client resources present in the Terraform state.

```bash
terraform state list | grep aws_cognito_user_pool_client
```

--------------------------------

### Advanced Security Configuration

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Configuration for advanced security flows remains identical before and after the migration.

```hcl
module "cognito_user_pool" {
  source = "lgallard/cognito-user-pool/aws"

  user_pool_name = "my-pool"
  user_pool_add_ons_advanced_security_mode              = "ENFORCED"
  user_pool_add_ons_advanced_security_additional_flows = "AUDIT"
}
```

```hcl
module "cognito_user_pool" {
  source = "lgallard/cognito-user-pool/aws"

  user_pool_name = "my-pool"
  user_pool_add_ons_advanced_security_mode              = "ENFORCED"
  user_pool_add_ons_advanced_security_additional_flows = "AUDIT"
}
```

--------------------------------

### Configure Terraform MCP Server

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Local configuration for the Terraform MCP server to enable documentation lookups.

```json
{
  "mcpServers": {
    "terraform": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-terraform@latest"]
    }
  }
}
```

--------------------------------

### Managed Login Branding Configuration

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the structure for managed login branding, including client IDs and asset configurations.

```hcl
map(object({
    client_id = string
    assets = optional(list(object({
      bytes       = string
      category    = string
      color_mode  = string
      extension   = string
      resource_id = optional(string)
    })), [])
    settings                    = optional(string)
    return_merged_resources     = optional(bool, false)
    use_cognito_provided_values = optional(bool, false)
  }))
```

--------------------------------

### Back up Terraform state

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Create a secure backup of the current state before performing migration operations.

```bash
terraform state pull | gpg --symmetric > pre-managed-login-branding-migration.tfstate.gpg
```

```bash
terraform state pull > pre-managed-login-branding-migration.tfstate
```

--------------------------------

### Email MFA Configuration Input

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the structure for email Multi-Factor Authentication settings.

```hcl
object({
    message = string
    subject = string
  })
```

--------------------------------

### Identity Providers Configuration Input

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the structure for configuring external identity providers.

```hcl
list(object({
    provider_name     = string
    provider_type     = string
    attribute_mapping = optional(map(string), {})
    idp_identifiers   = optional(list(string), [])
    provider_details  = optional(map(string), {})
  }))
```

--------------------------------

### Create Basic Cognito User Pool

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/simple/README.md

Use this module to create a basic AWS Cognito User Pool. It is recommended to set `ignore_schema_changes = true` to prevent perpetual diffs if custom schemas are added later.

```hcl
module "aws_cognito_user_pool_simple_example" {

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

  user_pool_name = "simple_pool"

  # Recommended: Enable schema ignore changes for new deployments
  # This prevents perpetual diffs if you plan to use custom schemas in the future
  ignore_schema_changes = true

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

--------------------------------

### Configure a complete AWS Cognito User Pool

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Deploys a fully configured Cognito User Pool including advanced security, custom schemas, and email settings. Ensure ignore_schema_changes is set to true to avoid perpetual diffs with custom schemas.

```hcl
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"]
  user_pool_tier           = "ESSENTIALS" # Valid values: LITE, ESSENTIALS, PLUS. Default is ESSENTIALS

  deletion_protection = "ACTIVE"

  # Advanced security configuration for user pool add-ons
  user_pool_add_ons_advanced_security_mode = "ENFORCED"
  user_pool_add_ons_advanced_security_additional_flows = "AUDIT"

  # IMPORTANT: Enable schema ignore changes to prevent perpetual diffs with custom schemas
  # This is ESSENTIAL for new deployments using custom schemas to avoid AWS API errors
  ignore_schema_changes = true

  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"
    from_email_address     = "noreply@example.com"
    configuration_set      = "my-configuration-set"
  }

  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
      }
    }
  ]

  recovery_mechanisms = [
     {
      name     = "verified_email"
      priority = 1
    },
    {
      name     = "verified_phone_number"
      priority = 2
    }
  ]

  sign_in_policy = {
    allowed_first_auth_factors = ["PASSWORD", "EMAIL_OTP", "SMS_OTP"]
  }

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

--------------------------------

### Migrate UI customization state

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Use this command to manually move state if Terraform proposes recreation due to address changes.

```bash
terraform state mv \
  'module.<your_module_name>.aws_cognito_user_pool_ui_customization.ui_customization["client-0"]' \
  'module.<your_module_name>.aws_cognito_user_pool_ui_customization.ui_customization["client_0"]'
```

--------------------------------

### Update Module Version

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Update the module source to version 5.0.0 or later in your configuration.

```hcl
module "cognito_user_pool" {
  source = "lgallard/cognito-user-pool/aws"
  version = "5.0.0"  # or latest version

  # Your existing configuration remains the same
  user_pool_name = "my-pool"
  # ... other settings
}
```

--------------------------------

### Migrate state resource address

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION.md

Move the branding resource from the AWSCC provider address to the native AWS provider address.

```bash
terraform state mv \
  'module.<your_module_name>.awscc_cognito_managed_login_branding.branding["main"]' \
  'module.<your_module_name>.aws_cognito_managed_login_branding.branding["main"]'
```

--------------------------------

### Migrate Terraform State for Cognito User Groups

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Use these commands to move existing user group resources from count-based indexing to stable, name-based identifiers in your Terraform state. This is crucial after updating the module to use for_each.

```bash
# Example: If you have groups named "admins", "users", "developers"
terraform state mv 'aws_cognito_user_group.main[0]' 'aws_cognito_user_group.main["admins"]'
terraform state mv 'aws_cognito_user_group.main[1]' 'aws_cognito_user_group.main["users"]'
terraform state mv 'aws_cognito_user_group.main[2]' 'aws_cognito_user_group.main["developers"]'
```

--------------------------------

### Configure Managed Login Branding in Terraform

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Enable branding by setting managed_login_branding_enabled to true and providing asset and settings configurations. Requires hashicorp/aws provider version 6.12.0 or higher.

```hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.12.0"
    }
  }
}

module "cognito_with_branding" {
  source = "lgallard/cognito-user-pool/aws"

  user_pool_name = "my-branded-pool"

  # Enable branding
  managed_login_branding_enabled = true

  # Branding configuration
  managed_login_branding = {
    "main-branding" = {
      client_id = "your-client-id"

      assets = [
        {
          bytes      = filebase64("./logo.png")
          category   = "FORM_LOGO"
          color_mode = "LIGHT"
          extension  = "png"
        }
      ]

      settings = jsonencode({
        "colorScheme" = {
          "light" = {
            "primary" = "#007bff"
          }
        }
      })
    }
  }
}
```

--------------------------------

### Configure Terraform Provider Version

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Defines the minimum required Terraform and AWS provider versions for the project.

```hcl
# Example provider configuration
terraform {
  required_version = ">= 1.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0"
    }
  }
}
```

--------------------------------

### Terraform Command for Cleanup

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/refresh_token_rotation/README.md

Command to destroy resources created by the Terraform configuration.

```bash
terraform destroy
```

--------------------------------

### Configure Cognito User Pool with Email MFA

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/email_mfa/README.md

Use this configuration to enable email-based MFA for your Cognito User Pool. Ensure AWS SES is set up and a valid SES source ARN is provided. At least two account recovery mechanisms are required.

```hcl
module "aws_cognito_user_pool_email_mfa_example" {
  source = "../../"

  user_pool_name = "email_mfa_pool"

  # Recommended: Enable schema ignore changes for new deployments
  # This prevents perpetual diffs if you plan to use custom schemas
  ignore_schema_changes = true

  # Email configuration
  email_configuration = {
    email_sending_account = "DEVELOPER"
    from_email_address    = "noreply@example.com"
    source_arn            = "arn:aws:ses:us-east-1:123456789012:identity/example.com"
    reply_to_email_address = "reply@example.com"
    configuration_set      = "my-configuration-set"
  }

  # Email MFA configuration
  email_mfa_configuration = {
    message = "Your verification code is {####}"
    subject = "Your verification code"
  }

  # Account recovery settings (required for email MFA)
  recovery_mechanisms = [
    {
      name     = "verified_email"
      priority = 1
    },
    {
      name     = "verified_phone_number"
      priority = 2
    }
  ]

  # MFA configuration
  mfa_configuration = "ON"

  # Auto verify email
  auto_verified_attributes = ["email"]
}
```

--------------------------------

### Define log_delivery_configuration structure

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the complex object structure required for configuring Cognito user pool log delivery to CloudWatch, Firehose, or S3.

```hcl
object({
    log_configurations = list(object({
      event_source = string
      log_level    = string

      cloud_watch_logs_configuration = optional(object({
        log_group_arn = string
      }))

      firehose_configuration = optional(object({
        stream_arn = string
      }))

      s3_configuration = optional(object({
        bucket_arn = string
      }))
    }))
  })
```

--------------------------------

### List Current Cognito User Groups in Terraform State

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

These commands help identify your existing user group names and their current state indexing. This information is necessary for performing the manual state migration.

```bash
# List current user groups in your state
terraform state list | grep aws_cognito_user_group
terraform state show 'aws_cognito_user_group.main[0]' | grep name
```

```bash
# ... continue for all groups
```

--------------------------------

### Show Details of a Specific Cognito User Pool Client

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Command to display detailed attributes of a specific aws_cognito_user_pool_client resource from the Terraform state, useful for identifying client names.

```bash
terraform state show 'aws_cognito_user_pool_client.client[0]' | grep name
```

--------------------------------

### Configure Terraform Variables

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/with_branding/README.md

Sets the essential variables for the User Pool name, domain, and AWS region.

```hcl
user_pool_name = "my-app-user-pool"
domain_name    = "my-app-auth"  # Optional custom domain
aws_region     = "us-east-1"
```

--------------------------------

### Add User to Cognito Group

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

After allowing Terraform to recreate Cognito user groups, use this command to restore user memberships. This is part of the alternative migration approach to avoid manual state manipulation.

```bash
aws cognito-idp admin-add-user-to-group --user-pool-id <pool_id> --group-name <group_name> --username <username>
```

--------------------------------

### Implement variable validation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/CLAUDE.md

Use validation blocks to enforce constraints on input variables, such as naming conventions.

```hcl
# Example: Basic validation for naming conventions
variable "user_pool_name" {
  description = "Name of the Cognito User Pool to create"
  type        = string
  default     = null

  validation {
    condition     = var.user_pool_name == null ? true : can(regex("^[0-9A-Za-z-_\\s]{1,128}$", var.user_pool_name))
    error_message = "The user_pool_name must be between 1 and 128 characters, contain only alphanumeric characters, spaces, hyphens, and underscores."
  }
}
```

--------------------------------

### Password Policy Configuration

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the schema for the user pool password policy settings.

```hcl
object({
    minimum_length                   = number,
    require_lowercase                = bool,
    require_numbers                  = bool,
    require_symbols                  = bool,
    require_uppercase                = bool,
    temporary_password_validity_days = number
    password_history_size            = number
  })
```

--------------------------------

### Export User Memberships from Cognito Group

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/MIGRATION_GUIDE.md

Before attempting an alternative migration approach that involves recreating groups, export user memberships from existing Cognito groups. This allows for restoration after the groups are recreated.

```bash
aws cognito-idp list-users-in-group --user-pool-id <pool_id> --group-name <group_name>
```

--------------------------------

### Destroy Terraform Resources

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/with_branding/README.md

Execute this command to remove all resources created by the Terraform configuration.

```bash
terraform destroy
```

--------------------------------

### Configure Refresh Token Rotation

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Defines the structure for enabling refresh token rotation and setting the retry grace period.

```hcl
object({
    feature                    = optional(string)
    retry_grace_period_seconds = optional(number)
  })
```

--------------------------------

### Configure Cognito log delivery

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Sets up log delivery for notification errors using a CloudWatch Log Group destination. Ensure the required IAM permissions are configured for the target log group.

```hcl
resource "aws_cloudwatch_log_group" "cognito_user_notification_errors" {
  name              = "/aws/vendedlogs/cognito/mypool/user-notification-errors"
  retention_in_days = 30
}

module "aws_cognito_user_pool_with_log_delivery" {
  source = "lgallard/cognito-user-pool/aws"

  user_pool_name        = "mypool"
  ignore_schema_changes = true

  log_delivery_configuration = {
    log_configurations = [
      {
        event_source = "userNotification"
        log_level    = "ERROR"

        cloud_watch_logs_configuration = {
          log_group_arn = aws_cloudwatch_log_group.cognito_user_notification_errors.arn
        }
      }
    ]
  }
}
```

--------------------------------

### Configure AWS Provider

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/with_branding/README.md

Defines the required AWS provider version for the Terraform configuration.

```hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.12.0"
    }
  }
}
```

--------------------------------

### Configure Cognito User Pool with Schema Ignore

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Use this configuration to enable the schema change ignore feature for new deployments.

```hcl
module "aws_cognito_user_pool" {
  source = "lgallard/cognito-user-pool/aws"

  user_pool_name = "mypool"

  # Enable this to prevent perpetual diffs with custom schemas
  ignore_schema_changes = true

  schemas = [
    {
      attribute_data_type      = "String"
      developer_only_attribute = false
      mutable                  = true
      name                     = "roles"
      required                 = false
    }
  ]

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

--------------------------------

### Configure Refresh Token Rotation in HCL

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/examples/refresh_token_rotation/README.md

Enable refresh token rotation and set a retry grace period. The grace period should not exceed 60 seconds as per AWS limits.

```hcl
refresh_token_rotation = {
  feature                    = "ENABLED"      # Enable rotation
  retry_grace_period_seconds = 60             # Maximum 60 seconds per AWS limits
}
```

--------------------------------

### Define Token Validity Units

Source: https://github.com/lgallard/terraform-aws-cognito-user-pool/blob/master/README.md

Sets the time units for access, ID, and refresh tokens.

```hcl
{
  "access_token": "minutes",
  "id_token": "minutes",
  "refresh_token": "days"
}
```