### Example Validation Workflow Before Release

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

This example shows how to request backward compatibility and documentation verification before releasing changes, using specific agents.

```plaintext
@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.
```

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

### Install pre-commit hooks

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

Install the pre-commit hooks into your local repository. These hooks run automatically before each commit.

```bash
pre-commit install
```

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

### Install required development tools

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

Install tfsec for security scanning and tflint for Terraform linting using Homebrew.

```bash
brew install tfsec
```

```bash
brew install tflint
```

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

### 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
```

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

### Example Validation Workflow for New Features

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

This example demonstrates a comprehensive validation workflow after implementing a new feature, requesting reviews from multiple specialized agents.

```plaintext
@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
```

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

### Install pre-commit hook manager

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

Install pre-commit using pip or brew. This tool manages pre-commit hooks for code quality checks.

```bash
pip install pre-commit
```

```bash
brew install pre-commit
```

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

### Development - Pre-commit Setup

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

Information on setting up and using pre-commit hooks for code quality and consistency within the development workflow.

```APIDOC
## Development

### Pre-commit Setup

This module uses [pre-commit](https://pre-commit.com/) hooks to ensure code quality and consistency. The pre-commit configuration includes:

#### Hooks Included

- **Code Quality:**
  - `terraform_fmt` - Automatic Terraform formatting
  - `terraform_validate` - Terraform syntax validation
  - `terraform_docs` - Automatic documentation generation
  - `terraform_tflint` - Terraform linting with identity-specific rules
  - `terraform_tfsec` - Security scanning for Cognito/IAM configurations

- **File Quality:**
  - `trailing-whitespace` - Remove trailing whitespace
  - `end-of-file-fixer` - Ensure files end with newline
  - `check-yaml` - YAML file validation
  - `check-json` - JSON file validation
  - `detect-aws-credentials` - Prevent AWS credential commits
  - `detect-private-key` - Prevent private key commits

- **Content Quality:**
  - `typos` - Markdown typo checking
```

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

### Create Multiple User Pool Clients with for_each

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

Example of creating multiple user pool clients using the for_each meta-argument for dynamic resource generation. This is preferred over count for better resource management.

```hcl
# Example: Creating multiple user pool clients
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
    }
  }
}
```

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

### Example AI validation request

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

An example request to Claude's AI agents for validating Terraform configurations, focusing on Cognito and security aspects.

```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.
```

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

### Module Usage with Advanced Security (Before Migration)

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

Example of how to configure advanced security additional flows before the AWS Provider 6.x migration. This syntax remains functional.

```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"
}
```

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

### Example Request for Modifications

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

Use this format when requesting validation for modifications to existing functionality, specifying relevant agents.

```plaintext
@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.
```

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

### Example Validation Workflow for Security Changes

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

Use this format to request a security analysis after updating account takeover prevention settings, ensuring adherence to best practices.

```plaintext
@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.
```

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

### 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"]'
```

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

### AI Validation Request Example

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

Example of how to request AI validation using specialized Claude Code subagents for reviewing new features, security implications, and best practices.

```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 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"]'
```

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

### 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"]'
```

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

### Example Request for Security-Critical Changes

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

Use this format to request security validation for critical changes, emphasizing the use of the terraform-security agent.

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

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

### Terraform Provider Requirements

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

Specifies the required Terraform and AWSCC provider versions for this example.

```hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.0"
    }
    awscc = {
      source  = "hashicorp/awscc"
      version = ">= 1.0"
    }
  }
}
```

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

### Terraform Provider Configuration

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

Example provider configuration specifying required Terraform and AWS provider versions. Version constraints should be chosen based on actual requirements and compatibility needs.

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

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

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

### Basic Validation for Naming Conventions

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

Implement validation blocks within variable definitions to enforce naming conventions and data types. This example validates the `user_pool_name` to ensure it meets specific criteria.

```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."
  }
}
```

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

### Create Complete Cognito User Pool with Detailed Configuration

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

This comprehensive example configures an AWS Cognito User Pool with detailed settings, including alias attributes, auto-verified attributes, user pool tier, advanced security, custom schemas, password policies, recovery mechanisms, and sign-in policies. Ensure `ignore_schema_changes` is set to `true` for custom schemas to prevent AWS API errors.

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

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

### 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

```

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

### Conditionally Create Cognito User Pool

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

This example demonstrates how to conditionally create a Cognito User Pool by setting the `enabled` variable to `false`. This is useful for managing resources across different Terraform versions or environments. For Terraform 0.14+, `count` can also be used.

```hcl
# This Cognito User Pool will not be created
module "aws_cognito_user_pool_conditional_creation" {
  source  = "lgallard/cognito-user-pool/aws"

  user_pool_name = "conditional_user_pool"

  enabled = false

  # 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
  }
}
```

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

### Terraform Password Policy Validation Example

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

This HCL snippet demonstrates how to define a password policy with validation rules for a Cognito User Pool, ensuring minimum length requirements.

```hcl
variable "password_policy" {
  description = "Password policy configuration for the user pool"
  type = object({
    minimum_length    = number
    require_lowercase = bool
    require_numbers   = bool
    require_symbols   = bool
    require_uppercase = bool
  })
  default = null

  validation {
    condition     = var.password_policy == null ? true : var.password_policy.minimum_length >= 6 && var.password_policy.minimum_length <= 99
    error_message = "Password minimum length must be between 6 and 99 characters."
  }
}
```

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

### Terraform Plan Output Showing Perpetual Diff

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

This example illustrates the perpetual difference that can occur in Terraform plans when managing Cognito User Pool schemas due to AWS API behavior.

```diff
- 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
}
```

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

### 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
```

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

### Run all pre-commit hooks

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

Execute all configured pre-commit hooks on all files in the repository. Useful for ensuring consistent code quality.

```bash
pre-commit run --all-files
```

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

### 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
```

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

### Run a specific pre-commit hook

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

Execute a single pre-commit hook, such as 'terraform_fmt' for formatting or 'terraform_tfsec' for security scanning.

```bash
pre-commit run terraform_fmt
```

```bash
pre-commit run terraform_tfsec
```

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

### Terraform Migration Commands

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

Provides the necessary commands to initialize, plan, and apply Terraform changes after updating the provider and module versions.

```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
```

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

### MCP Server Configuration for Context7

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

Local configuration for the Context7 MCP Server, used to access general library and framework documentation. This configuration specifies the command and arguments to run the server.

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

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

### Prefer for_each over count for Resource Creation

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

Use `for_each` for creating multiple instances of a resource when you have a map or set of strings. This is generally preferred over `count` as it provides more stable and readable resource addressing.

```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
  # ...
}
```

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

### Cognito Advanced Security Configuration - AWS Provider 6.x Syntax

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

Demonstrates the current syntax for `advanced_security_additional_flows` required for AWS Provider 6.x, utilizing a dynamic block.

```hcl
user_pool_add_ons {
  advanced_security_mode = "ENFORCED"

  dynamic "advanced_security_additional_flows" {
    for_each = var.advanced_security_additional_flows != null ? [1] : []
    content {
      custom_auth_mode = var.advanced_security_additional_flows
    }
  }
}
```

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

### 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
```

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

### Terraform Migration Commands for Existing Deployments

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

Commands to migrate an existing Terraform deployment to use the schema change ignore fix. This involves planning, applying, and moving state.

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

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

### Structure Locals for Clarity and Reusability

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

Organize locals to define conditions, process data, and create helper variables. This improves readability and maintainability of Terraform configurations.

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

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

### Run pre-commit hooks on staged files

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

Execute pre-commit hooks only on files that are currently staged for commit. This is the default behavior.

```bash
pre-commit run
```

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

### Cognito Advanced Security Configuration - AWS Provider 5.x Syntax

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

Illustrates the deprecated syntax for `advanced_security_additional_flows` used with AWS Provider 5.x.

```hcl
user_pool_add_ons {
  advanced_security_mode              = "ENFORCED"
  advanced_security_additional_flows = var.advanced_security_additional_flows
}
```

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

### 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
  }
}
```

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

### Troubleshooting: Invalid Argument - advanced_security_additional_flows Error

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

Indicates that the AWS provider version is still 5.x, causing the `advanced_security_additional_flows` argument to be invalid. The solution requires updating the provider and running Terraform commands.

```text
Invalid argument - advanced_security_additional_flows
```

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

### Manual Feature Discovery Trigger

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

Manually trigger the feature discovery workflow using the GitHub CLI. Options include standard discovery, dry runs, specifying a provider version, or forcing a full scan.

```bash
gh workflow run feature-discovery.yml
```

```bash
gh workflow run feature-discovery.yml -f dry_run=true
```

```bash
gh workflow run feature-discovery.yml -f provider_version=5.82.0
```

```bash
gh workflow run feature-discovery.yml -f force_scan=true
```

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

### 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"]'
```

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

### Create Simple Cognito User Pool

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

Use this snippet to create a basic AWS Cognito User Pool with default settings. It's recommended to enable schema ignore changes for new deployments to prevent perpetual diffs with custom schemas.

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

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

### Outputs

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

Available output values from the Cognito User Pool module.

```APIDOC
## Outputs

### arn
The ARN of the user pool

### client_ids
The ids of the user pool clients

### client_ids_map
The ids map of the user pool clients

### client_secrets
The client secrets of the user pool clients

### client_secrets_map
The client secrets map of the user pool clients

### creation_date
The date the user pool was created

### domain_app_version
The app version

### domain_aws_account_id
The AWS account ID for the user pool owner

### domain_cloudfront_distribution
The name of the CloudFront distribution

### domain_cloudfront_distribution_arn
The ARN of the CloudFront distribution

### domain_cloudfront_distribution_zone_id
The ZoneID of the CloudFront distribution

### domain_s3_bucket
The S3 bucket where the static files for this domain are stored

### endpoint
The endpoint name of the user pool. Example format: cognito-idp.REGION.amazonaws.com/xxxx_yyyyy

### id
The id of the user pool

### last_modified_date
The date the user pool was last modified

### managed_login_branding
Map of managed login branding configurations (deprecated - use managed_login_branding_details)

### managed_login_branding_details
Complete managed login branding details

### managed_login_branding_ids
Map of managed login branding IDs (deprecated - use managed_login_branding_details.ids)

### name
The name of the user pool

### resource_servers_scope_identifiers
A list of all scopes configured in the format identifier/scope_name

### user_group_arns
The ARNs of the user groups

### user_group_ids
The ids of the user groups

### user_group_names
The names of the user groups

### user_groups_map
A map of user group names to their properties
```

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

### 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 Clients

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

This configuration supports both legacy and new client formats for Cognito User Pools. It uses flatten to combine configurations from various input variables.

```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, [])])]
])
```

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

### 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"]
}
```

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

### 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
```

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

### Terraform Variables Configuration

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

Sets up essential variables for the Cognito User Pool, including name, domain, and region.

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

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

### 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
```

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

### 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>
```

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

### MCP Server Configuration for Terraform

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

Local configuration for the Terraform MCP Server, used to access up-to-date Terraform and AWS provider documentation. This configuration specifies the command and arguments to run the server.

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

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

### 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>
```

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

### Configure Terraform Providers and Cognito User Pool with Branding

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

This snippet shows how to configure the AWS and AWSCC providers and enable managed login branding for a Cognito user pool. Ensure the awscc provider is included for branding features. The managed_login_branding block configures assets and settings.

```hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.0"
    }
    awscc = {
      source  = "hashicorp/awscc"
      version = ">= 1.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"
          }
        }
      })
    }
  }
}
```

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

### Input Variable: verification_message_template_sms_message

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

Configuration for the SMS message template used for verification. This template must include the {####} placeholder for the verification code. It conflicts with the `sms_verification_message` argument.

```APIDOC
## Input Variable: verification_message_template_sms_message

### Description
SMS message template. Must contain the {####} placeholder. Conflicts with sms_verification_message argument.

### Type
`string`

### Default
`null`

### Required
no
```

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

### Troubleshooting: Module Requires Newer AWS Provider Error

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

Displays the error message indicating an outdated AWS provider version. The solution involves updating the provider constraint and re-initializing Terraform.

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

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

### 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
}
```

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

### Feature Tracking JSON Structure

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

This JSON file tracks the implementation status of Cognito User Pool features, including metadata, current implementation details, and discovered features. It is used for automated monitoring and validation.

```json
{
  "metadata": {
    "last_scan": "2025-01-21T00:00:00Z",
    "provider_version": "5.82.0",
    "scan_count": 42
  },
  "current_implementation": {
    "resources": {
      "aws_cognito_user_pool": {
        "implemented": ["name", "mfa_configuration", "password_policy"],
        "pending": ["advanced_security_mode"]
      }
    }
  },
  "discovered_features": {
    "new_resources": {},
    "deprecations": {},
    "bug_fixes": {}
  }
}
```

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

### Cognito User Pool Configuration

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

Defines the main configuration for an AWS Cognito User Pool, including attributes, domain, clients, user groups, resource servers, and identity providers.

```hcl
resource "aws_cognito_user_pool" "main" {
  # ... other configurations ...

  attributes {
    name = "mynumber2"
    required = false

    number_attribute_constraints {
      min_value = 2
      max_value = 6
    }
  }

  # user_pool_domain
  domain = "mydomain-com"

  # clients
  clients = [
    {
      allowed_oauth_flows                  = []
      allowed_oauth_flows_user_pool_client = false
      allowed_oauth_scopes                 = []
      callback_urls                        = ["https://mydomain.com/callback"]
      default_redirect_uri                 = "https://mydomain.com/callback"
      explicit_auth_flows                  = []
      generate_secret                      = true
      logout_urls                          = []
      name                                 = "test1"
      read_attributes                      = ["email"]
      supported_identity_providers         = []
      write_attributes                     = []
      access_token_validity                = 1
      id_token_validity                    = 1
      refresh_token_validity               = 60
      token_validity_units = {
        access_token  = "hours"
        id_token      = "hours"
        refresh_token = "days"
      }
    },
    {
      allowed_oauth_flows                  = []
      allowed_oauth_flows_user_pool_client = false
      allowed_oauth_scopes                 = []
      callback_urls                        = ["https://mydomain.com/callback"]
      default_redirect_uri                 = "https://mydomain.com/callback"
      explicit_auth_flows                  = []
      generate_secret                      = false
      logout_urls                          = []
      name                                 = "test2"
      read_attributes                      = []
      supported_identity_providers         = []
      write_attributes                     = []
      refresh_token_validity               = 30
    },
    {
      allowed_oauth_flows                  = ["code", "implicit"]
      allowed_oauth_flows_user_pool_client = true
      allowed_oauth_scopes                 = ["email", "openid"]
      callback_urls                        = ["https://mydomain.com/callback"]
      default_redirect_uri                 = "https://mydomain.com/callback"
      explicit_auth_flows                  = ["CUSTOM_AUTH_FLOW_ONLY", "ADMIN_NO_SRP_AUTH"]
      generate_secret                      = false
      logout_urls                          = ["https://mydomain.com/logout"]
      name                                 = "test3"
      read_attributes                      = ["email", "phone_number"]
      supported_identity_providers         = []
      write_attributes                     = ["email", "gender", "locale", ]
      refresh_token_validity               = 30
      prevent_user_existence_errors        = "ENABLED"
    }
  ]

  # user_group
  user_groups = [
    {
      name        = "mygroup1"
      description = "My group 1"
    },
    {
      name        = "mygroup2"
      description = "My group 2"
    },
  ]

  # resource_servers
  resource_servers = [
    {
      identifier = "https://mydomain.com"
      name       = "mydomain"
      scope = [
        {
          scope_name        = "sample-scope-1"
          scope_description = "A sample Scope Description for mydomain.com"
        },
        {
          scope_name        = "sample-scope-2"
          scope_description = "Another sample Scope Description for mydomain.com"
        },
      ]
    },
    {
      identifier = "https://weather-read-app.com"
      name       = "weather-read"
      scope = [
        {
          scope_name        = "weather.read"
          scope_description = "Read weather forecasts"
        }
      ]
    }
  ]

  # identity_providers
  identity_providers = [
    {
      provider_name = "Google"
      provider_type = "Google"

      provider_details = {
        authorize_scopes = "email"
        client_id        = "your client_id"
        client_secret    = "your client_secret"
      }

      attribute_mapping = {
        email    = "email"
        username = "sub"
        gender   = "gender"
      }
    }
  ]

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