cognito

This component is responsible for provisioning and managing AWS Cognito resources.

This component can provision the following resources:

• Cognito User Pools
• Cognito User Pool Clients
• Cognito User Pool Domains
• Cognito User Pool Identity Providers
• Cognito User Pool Resource Servers
• Cognito User Pool User Groups

Usage

Stack Level: Global

Here's an example snippet for how to use this component:

components:
  terraform:
    cognito:
      settings:
        spacelift:
          workspace_enabled: true
      vars:
        enabled: true
        # The full name of the User Pool will be: <namespace>-<environment>-<stage>-<name>
        name: cognito
        schemas:
          - name: "email"
            attribute_data_type: "String"
            developer_only_attribute: false
            mutable: false
            required: true

Variables

Required Variables

region (string) required

AWS region

Optional Variables

admin_create_user_config (map(any)) optional

The configuration for AdminCreateUser requests

Default value: { }

admin_create_user_config_allow_admin_create_user_only (bool) optional

Set to true if only the administrator is allowed to create user profiles. Set to false if users can sign themselves up via an app

Default value: true

admin_create_user_config_email_message (string) optional

The message template for email messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively

Default value: "{username}, your temporary password is {####}"

admin_create_user_config_email_subject (string) optional

The subject line for email messages

Default value: "Your verification code"

admin_create_user_config_sms_message (string) optional

The message template for SMS messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively

Default value: "Your username is {username} and temporary password is {####}"

alias_attributes (list(string)) optional

Attributes supported as an alias for this user pool. Possible values: phone_number, email, or preferred_username. Conflicts with username_attributes

Default value: null

auto_verified_attributes (list(string)) optional

The attributes to be auto-verified. Possible values: email, phone_number

Default value: [ ]

client_access_token_validity (number) optional

Time limit, between 5 minutes and 1 day, after which the access token is no longer valid and cannot be used. This value will be overridden if you have entered a value in token_validity_units.

Default value: 60

client_allowed_oauth_flows (list(string)) optional

List of allowed OAuth flows (code, implicit, client_credentials)

Default value: [ ]

client_allowed_oauth_flows_user_pool_client (bool) optional

Whether the client is allowed to follow the OAuth protocol when interacting with Cognito user pools

Default value: true

client_allowed_oauth_scopes (list(string)) optional

List of allowed OAuth scopes (phone, email, openid, profile, and aws.cognito.signin.user.admin)

Default value: [ ]

client_callback_urls (list(string)) optional

List of allowed callback URLs for the identity providers

Default value: [ ]

client_default_redirect_uri (string) optional

The default redirect URI. Must be in the list of callback URLs

Default value: ""

client_explicit_auth_flows (list(string)) optional

List of authentication flows (ADMIN_NO_SRP_AUTH, CUSTOM_AUTH_FLOW_ONLY, USER_PASSWORD_AUTH)

Default value: [ ]

client_generate_secret (bool) optional

Should an application secret be generated

Default value: true

client_id_token_validity (number) optional

Time limit, between 5 minutes and 1 day, after which the ID token is no longer valid and cannot be used. Must be between 5 minutes and 1 day. Cannot be greater than refresh token expiration. This value will be overridden if you have entered a value in token_validity_units.

Default value: 60

client_logout_urls (list(string)) optional

List of allowed logout URLs for the identity providers

Default value: [ ]

client_name (string) optional

The name of the application client

Default value: null

client_prevent_user_existence_errors (string) optional

Choose which errors and responses are returned by Cognito APIs during authentication, account confirmation, and password recovery when the user does not exist in the user pool. When set to ENABLED and the user does not exist, authentication returns an error indicating either the username or password was incorrect, and account confirmation and password recovery return a response indicating a code was sent to a simulated destination. When set to LEGACY, those APIs will return a UserNotFoundException exception if the user does not exist in the user pool.

Default value: null

client_read_attributes (list(string)) optional

List of user pool attributes the application client can read from

Default value: [ ]

client_refresh_token_validity (number) optional

The time limit in days refresh tokens are valid for. Must be between 60 minutes and 3650 days. This value will be overridden if you have entered a value in token_validity_units

Default value: 30

client_supported_identity_providers (list(string)) optional

List of provider names for the identity providers that are supported on this client

Default value: [ ]

client_token_validity_units (any) optional

Configuration block for units in which the validity times are represented in. Valid values for the following arguments are: seconds, minutes, hours or days.

Default value:

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

client_write_attributes (list(string)) optional

List of user pool attributes the application client can write to

Default value: [ ]

clients (any) optional

User Pool clients configuration

Default value: [ ]

deletion_protection (string) optional

(Optional) When active, DeletionProtection prevents accidental deletion of your user pool. Before you can delete a user pool that you have protected against deletion, you must deactivate this feature. Valid values are ACTIVE and INACTIVE, Default value is INACTIVE.

Default value: "INACTIVE"

device_configuration (map(any)) optional

The configuration for the user pool's device tracking

Default value: { }

device_configuration_challenge_required_on_new_device (bool) optional

Indicates whether a challenge is required on a new device. Only applicable to a new device

Default value: false

device_configuration_device_only_remembered_on_user_prompt (bool) optional

If true, a device is only remembered on user prompt

Default value: false

domain (string) optional

Cognito User Pool domain

Default value: null

domain_certificate_arn (string) optional

The ARN of an ISSUED ACM certificate in us-east-1 for a custom domain

Default value: null

email_configuration (map(any)) optional

Email configuration

Default value: { }

email_configuration_email_sending_account (string) optional

Instruct Cognito to either use its built-in functionality or Amazon SES to send out emails. Allowed values: COGNITO_DEFAULT or DEVELOPER

Default value: "COGNITO_DEFAULT"

email_configuration_from_email_address (string) optional

Sender’s email address or sender’s display name with their email address (e.g. [email protected], John Smith <[email protected]> or "John Smith Ph.D." <[email protected]>). Escaped double quotes are required around display names that contain certain characters as specified in RFC 5322

Default value: null

email_configuration_reply_to_email_address (string) optional

The REPLY-TO email address

Default value: ""

email_configuration_source_arn (string) optional

The ARN of the email configuration source

Default value: ""

email_verification_message (string) optional

A string representing the email verification message

Default value: null

email_verification_subject (string) optional

A string representing the email verification subject

Default value: null

identity_providers (list(any)) optional

Cognito Identity Providers configuration

Default value: [ ]

lambda_config (any) optional

Configuration for the AWS Lambda triggers associated with the User Pool

Default value: null

lambda_config_create_auth_challenge (string) optional

The ARN of the lambda creating an authentication challenge

Default value: ""

lambda_config_custom_email_sender (map(any)) optional

A custom email sender AWS Lambda trigger

Default value: { }

lambda_config_custom_message (string) optional

AWS Lambda trigger custom message

Default value: ""

lambda_config_custom_sms_sender (map(any)) optional

A custom SMS sender AWS Lambda trigger

Default value: { }

lambda_config_define_auth_challenge (string) optional

Authentication challenge

Default value: ""

lambda_config_kms_key_id (string) optional

The Amazon Resource Name of Key Management Service Customer master keys. Amazon Cognito uses the key to encrypt codes and temporary passwords sent to CustomEmailSender and CustomSMSSender.

Default value: null

lambda_config_post_authentication (string) optional

A post-authentication AWS Lambda trigger

Default value: ""

lambda_config_post_confirmation (string) optional

A post-confirmation AWS Lambda trigger

Default value: ""

lambda_config_pre_authentication (string) optional

A pre-authentication AWS Lambda trigger

Default value: ""

lambda_config_pre_sign_up (string) optional

A pre-registration AWS Lambda trigger

Default value: ""

lambda_config_pre_token_generation (string) optional

Allow to customize identity token claims before token generation

Default value: ""

lambda_config_user_migration (string) optional

The user migration Lambda config type

Default value: ""

lambda_config_verify_auth_challenge_response (string) optional

Verifies the authentication challenge response

Default value: ""

mfa_configuration (string) optional

Multi-factor authentication configuration. Must be one of the following values (ON, OFF, OPTIONAL)

Default value: "OFF"

number_schemas (list(any)) optional

A container with the number schema attributes of a user pool. Maximum of 50 attributes

Default value: [ ]

password_policy optional

User Pool password policy configuration

Type:

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

Default value: null

password_policy_minimum_length (number) optional

The minimum password length

Default value: 8

password_policy_require_lowercase (bool) optional

Whether you have required users to use at least one lowercase letter in their password

Default value: true

password_policy_require_numbers (bool) optional

Whether you have required users to use at least one number in their password

Default value: true

password_policy_require_symbols (bool) optional

Whether you have required users to use at least one symbol in their password

Default value: true

password_policy_require_uppercase (bool) optional

Whether you have required users to use at least one uppercase letter in their password

Default value: true

password_policy_temporary_password_validity_days (number) optional

Password policy temporary password validity_days

Default value: 7

recovery_mechanisms (list(any)) optional

List of account recovery options

Default value: [ ]

resource_server_identifier (string) optional

Resource server identifier

Default value: null

resource_server_name (string) optional

Resource server name

Default value: null

resource_server_scope_description (string) optional

Resource server scope description

Default value: null

resource_server_scope_name (string) optional

Resource server scope name

Default value: null

resource_servers (list(any)) optional

Resource servers configuration

Default value: [ ]

schemas (list(any)) optional

A container with the schema attributes of a User Pool. Maximum of 50 attributes

Default value: [ ]

sms_authentication_message (string) optional

A string representing the SMS authentication message

Default value: null

sms_configuration (map(any)) optional

SMS configuration

Default value: { }

sms_configuration_external_id (string) optional

The external ID used in IAM role trust relationships

Default value: ""

sms_configuration_sns_caller_arn (string) optional

The ARN of the Amazon SNS caller. This is usually the IAM role that you've given Cognito permission to assume

Default value: ""

sms_verification_message (string) optional

A string representing the SMS verification message

Default value: null

software_token_mfa_configuration (map(any)) optional

Configuration block for software token MFA. mfa_configuration must also be enabled for this to work

Default value: { }

software_token_mfa_configuration_enabled (bool) optional

If true, and if mfa_configuration is also enabled, multi-factor authentication by software TOTP generator will be enabled

Default value: false

string_schemas (list(any)) optional

A container with the string schema attributes of a user pool. Maximum of 50 attributes

Default value: [ ]

temporary_password_validity_days (number) optional

The user account expiration limit, in days, after which the account is no longer usable

Default value: 7

user_group_description (string) optional

The description of the user group

Default value: null

user_group_name (string) optional

The name of the user group

Default value: null

user_group_precedence (number) optional

The precedence of the user group

Default value: null

user_group_role_arn (string) optional

The ARN of the IAM role to be associated with the user group

Default value: null

user_groups (list(any)) optional

User groups configuration

Default value: [ ]

user_pool_add_ons (map(any)) optional

Configuration block for user pool add-ons to enable user pool advanced security mode features

Default value: { }

user_pool_add_ons_advanced_security_mode (string) optional

The mode for advanced security, must be one of OFF, AUDIT or ENFORCED

Default value: null

user_pool_name (string) optional

User pool name. If not provided, the name will be generated from the context

Default value: null

username_attributes (list(string)) optional

Specifies whether email addresses or phone numbers can be specified as usernames when a user signs up. Conflicts with alias_attributes

Default value: null

username_configuration (map(any)) optional

The Username Configuration. Setting case_sensitive specifies whether username case sensitivity will be applied for all users in the user pool through Cognito APIs

Default value: { }

verification_message_template (map(any)) optional

The verification message templates configuration

Default value: { }

verification_message_template_default_email_option (string) optional

The default email option. Must be either CONFIRM_WITH_CODE or CONFIRM_WITH_LINK. Defaults to CONFIRM_WITH_CODE

Default value: null

verification_message_template_email_message_by_link (string) optional

The email message template for sending a confirmation link to the user, it must contain the {##Click Here##} placeholder

Default value: null

verification_message_template_email_subject_by_link (string) optional

The subject line for the email message template for sending a confirmation link to the user

Default value: null

Context Variables

The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.

additional_tag_map (map(string)) optional

Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.

Required: No

Default value: { }

attributes (list(string)) optional

ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.

Required: No

Default value: [ ]

context (any) optional

Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.

Required: No

Default value:

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

delimiter (string) optional

Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.

Required: No

Default value: null

descriptor_formats (any) optional

Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).

Required: No

Default value: { }

enabled (bool) optional

Set to false to prevent the module from creating any resources
Required: No

Default value: null

environment (string) optional

ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: No

Default value: null

id_length_limit (number) optional

Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.

Required: No

Default value: null

label_key_case (string) optional

Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.

Required: No

Default value: null

label_order (list(string)) optional

The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.

Required: No

Default value: null

label_value_case (string) optional

Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.

Required: No

Default value: null

labels_as_tags (set(string)) optional

Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.

Required: No

Default value:

[
  "default"
]

name (string) optional

ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.

Required: No

Default value: null

namespace (string) optional

ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: No

Default value: null

regex_replace_chars (string) optional

Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.

Required: No

Default value: null

stage (string) optional

ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: No

Default value: null

tags (map(string)) optional

Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.

Required: No

Default value: { }

tenant (string) optional

ID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: No

Default value: null

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 for the domain

domain_aws_account_id

The AWS account ID for the User Pool domain

domain_cloudfront_distribution_arn

The ARN of the CloudFront distribution for the domain

domain_s3_bucket

The S3 bucket where the static files for the 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

resource_servers_scope_identifiers

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

Dependencies

Requirements

• terraform, version: >= 1.0.0
• aws, version: >= 4.8.0

Providers

• aws, version: >= 4.8.0

Modules

Name	Version	Source	Description
iam_roles	latest	../account-map/modules/iam-roles	n/a
this	0.25.0	cloudposse/label/null	n/a

Resources

The following resources are used by this module:

• aws_cognito_identity_provider.identity_provider (resource)
• aws_cognito_resource_server.resource (resource)
• aws_cognito_user_group.main (resource)
• aws_cognito_user_pool.pool (resource)
• aws_cognito_user_pool_client.client (resource)
• aws_cognito_user_pool_domain.domain (resource)

Data Sources

The following data sources are used by this module:

References

• cloudposse/terraform-aws-components - Cloud Posse's upstream component