使用 Terraform AWS Provider 构建 Cognito User Pool：完整示例与配置详解

使用 Terraform AWS Provider 构建 Cognito User Pool完整示例与配置详解【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws导读本文围绕terraform-provider-aws仓库中的 Cognito User Pool 示例完整讲解如何使用 Terraform 声明式创建 Amazon Cognito User Pool用户池并集成 IAM 角色与 Lambda 触发器。读完本文你将掌握用户池核心配置块密码策略、Schema 属性、验证消息模板、SMS/邮件配置、Lambda 触发器的每一项参数含义与取值约束如何为 Cognito 服务与 Lambda 函数正确授权 IAM 角色以及terraform plan / apply / destroy的完整运维流程。示例源码位于 examples/cognito-user-pool/main.tf对应的 Provider 实现为internal/service/cognitoidp/user_pool.go本文将以源码为准补充参数约束与默认值确保示例可直接落地为真实配置。一、示例概览一次性交付用户池 IAM Lambda该示例在单个.tf文件中完成了三件事资源作用在本示例中的角色aws_iam_role.mainLambda 执行角色让 Lambda 以lambda.amazonaws.com服务身份运行aws_lambda_function.main用户池触发器函数承载用户池各类生命周期钩子aws_iam_role.cidpCognito 身份池服务角色允许 Cognito 代表用户池调用 SNS 发送短信aws_iam_role_policy.main角色内联策略授予sns:publish权限aws_cognito_user_pool.pool用户池核心资源本文讲解的主体模块入口examples/cognito-user-pool/main.tf中声明了provider aws区域取自 variables.tf 中的var.aws_region默认值为us-west-2同时约束了 Terraform 版本 0.12。从源码结构看示例是一个最小可运行的闭环Cognito 在发送短信验证码时通过aws_iam_role.cidp调用 SNS而邮件与短信内容模板、密码策略、属性 Schema 等都由用户池资源自身配置无需额外云资源。二、运行示例plan / apply / destroy 全流程原文档给出了三阶段的 CLI 操作这里补充每步的预期输出与用途# 1. 规划阶段对比声明与当前云资源输出将要执行的变更 terraform plan # 2. 应用阶段实际创建/更新资源并生成 terraform.tfstate 状态文件 terraform apply # 3. 销毁阶段按 key_name 变量指定参数拆除整个栈 terraform destroy -var key_name{your_key_name}terraform plan只做差异分析dry-run不触碰真实资源建议在任何apply前先执行确认预期变更符合意图。terraform apply会提示输入确认除非带-auto-approve执行后资源 ID 会写入 state。terraform destroy依次删除用户池、Lambda 函数与 IAM 角色示例中原文档在 destroy 时使用-var传入key_name此处变量并非本示例variables.tf中定义属于文档遗留示例实际使用时请根据自己定义的变量名传入对应值。注意Terraform 对aws_cognito_user_pool默认是幂等的重复apply不会产生额外资源删除用户池前请确认没有关联的 App Client、Domain 等依赖否则需先解除。三、Provider 实现为示例背书aws_cognito_user_pool的完整参数面示例中使用的每一项配置都能在 Provider 源码 internal/service/cognitoidp/user_pool.go 的 Schema 定义中找到对应字段。下表汇总了示例涉及的核心参数及其约束参数块/字段位置源码行号类型与约束默认值alias_attributesuser_pool.goL121-130SetStringForceNew与username_attributes互斥无auto_verified_attributesL135-142SetString取值受awstypes.VerifiedAttributeType枚举约束无email_verification_subject/email_verification_messageL241-254与verification_message_template.0.email_subject/email_message冲突无lambda_configL263-387ListMaxItems1内部字段大多为ValidARN校验的 ARN 字符串无password_policyL407-448ListMaxItems1minimum_length范围 6~99password_history_size0~24temporary_password_validity_days0~365见下文schemaL449-533SetMinItems1MaxItems50attribute_data_type受枚举约束无sms_configurationL539-563ListMaxItems1external_id必填sns_caller_arn必填且需合法 ARN无verification_message_templateL666-714ListMaxItems1default_email_option默认CONFIRM_WITH_CODECONFIRM_WITH_CODEsms_verification_messageL564-570与verification_message_template.0.sms_message冲突无email_configuration.reply_to_email_addressL199-207需匹配邮箱正则无mfa_configurationL392-397默认OFFOFF3.1 别名与自动验证属性alias_attributes允许用户使用email、preferred_username等作为登录别名源码中该字段标记ForceNew: trueL124意味着修改后会触发资源重建且与username_attributes互斥L129。auto_verified_attributes声明注册后自动完成验证的属性示例中选择[email]即用户注册时 Cognito 自动发送验证码并验证邮箱。3.2 验证消息模板示例同时使用了顶层email_verification_subject / email_verification_message / sms_verification_message与嵌套verification_message_templateemail_verification_subject Device Verification Code email_verification_message Please use the following code {####} sms_verification_message {####} Baz verification_message_template { default_email_option CONFIRM_WITH_CODE }源码中这两组字段被标记为ConflictsWith互斥L246、L253、L569因此实际生产配置中二选一即可示例同时列出是为了展示两种写法。{####}是 Cognito 约定的验证码占位符消息内容须包含该占位符才能通过校验见validUserPoolTemplateEmailMessage等校验函数。default_email_option支持CONFIRM_WITH_CODE与CONFIRM_WITH_LINK两种取值默认CONFIRM_WITH_CODEL673-678。3.3 密码策略password_policy { minimum_length 10 require_lowercase false require_numbers true require_symbols false require_uppercase true }源码约束minimum_length范围 6~99L417另外可配置password_history_size0~24与temporary_password_validity_days0~365。示例刻意关闭小写与符号要求、强制数字与大小写演示了灵活组合。3.4 Schema 属性定义示例定义了两个自定义属性schema { attribute_data_type String developer_only_attribute false mutable false name email required true string_attribute_constraints { min_length 7 max_length 15 } } schema { attribute_data_type Number developer_only_attribute true mutable true name mynumber required false number_attribute_constraints { min_value 2 max_value 6 } }源码限制整个schema集合最多 50 项L453attribute_data_type只能取枚举定义的类型String/Number/DateTime/Boolean 等L460。注意示例中 String 属性把min_length设为 7、max_length设为 15——这意味着用户邮箱必须满足该长度范围实际部署时建议按真实邮箱长度调整。此外mutable false表示该属性创建后不可修改required true表示注册时必填。四、IAM 授权链路Lambda 与 SNS 的两种信任模型示例用两个 IAM 角色展示了 Terraform 中最常见的两种服务授权模式。4.1 Lambda 执行角色aws_iam_role.mainresource aws_iam_role main { name terraform-example-lambda assume_role_policy EOF { Version: 2012-10-17, Statement: [ { Action: sts:AssumeRole, Principal: { Service: lambda.amazonaws.com }, Effect: Allow, Sid: } ] } EOF }信任策略Trust Policy声明谁可以扮演这个角色——此处允许 AWS Lambda 服务代入。该角色随后被aws_lambda_function.main通过role aws_iam_role.main.arn引用main.tf L35构成「函数 → 角色」的绑定。4.2 Cognito 服务角色aws_iam_role.cidpresource aws_iam_role cidp { name terraform-example-cognito-idp path /service-role/ assume_role_policy POLICY { Version: 2012-10-17, Statement: [ { Sid: , Effect: Allow, Principal: { Service: cognito-idp.amazonaws.com }, Action: sts:AssumeRole, Condition: { StringEquals: { sts:ExternalId: 12345 } } } ] } POLICY }关键点在于Condition.sts:ExternalId——Cognito 在代入该角色时必须携带外部 ID12345这为跨账户信任增加了安全护栏。同时注意角色路径设为/service-role/符合 AWS 管理控制台创建服务角色时的默认路径惯例该角色的external_id与用户池sms_configuration.external_idmain.tf L157必须一致否则短信发送会因信任校验失败。4.3 内联策略只给最小权限resource aws_iam_role_policy main { name terraform-example-cognito-idp role aws_iam_role.cidp.id policy EOF { Version: 2012-10-17, Statement: [ { Effect: Allow, Action: [sns:publish], Resource: [*] } ] } EOF }该策略通过role aws_iam_role.cidp.id挂到 Cognito 服务角色上只开放sns:publish——即用户池发送短信验证码时所需的唯一权限。sns_caller_arn aws_iam_role.cidp.arnmain.tf L158在用户池侧完成引用闭环。五、Lambda 触发器lambda_config的十个钩子与 V2 版本演进示例将同一个Lambda 函数同时挂到用户池的全部生命周期钩子上便于演示生产环境通常按钩子拆分不同函数lambda_config { create_auth_challenge aws_lambda_function.main.arn custom_message aws_lambda_function.main.arn define_auth_challenge aws_lambda_function.main.arn post_authentication aws_lambda_function.main.arn post_confirmation aws_lambda_function.main.arn pre_authentication aws_lambda_function.main.arn pre_sign_up aws_lambda_function.main.arn pre_token_generation aws_lambda_function.main.arn user_migration aws_lambda_function.main.arn verify_auth_challenge_response aws_lambda_function.main.arn pre_token_generation_config { lambda_arn aws_lambda_function.main.arn lambda_version V2_0 } }每个钩子的语义与源码位置触发器触发时机典型用途pre_sign_up用户注册前自定义注册校验、风控post_confirmation确认注册后初始化用户数据、发欢迎邮件pre_authentication登录认证前阻断/放行登录post_authentication认证成功后审计、更新最后登录时间custom_message发送验证码/邀请前定制邮件与短信内容define_auth_challenge自定义认证挑战定义无密码认证流程create_auth_challenge创建挑战时生成 MFA 挑战verify_auth_challenge_response校验挑战答案自定义 MFA 校验user_migration首次登录时从旧系统迁移用户pre_token_generation签发 Token 前注入自定义 Claims源码中这些字段均为ValidateFunc: verify.ValidARNL269-383即只能填合法 ARN。值得注意的演进源码 L349-374 中pre_token_generation标记为Optional Computed而新增的pre_token_generation_config子块要求同时提供lambda_arn与lambda_versionV2_0等受awstypes.PreTokenGenerationLambdaVersionType枚举约束。示例注释也指出pre_token_generation字段保留是为了兼容旧配置新配置应使用pre_token_generation_config并让两者 ARN 保持一致。对应验收测试TestAccCognitoIDPUserPool_withLambdauser_pool_test.go L1264-1303会逐一断言lambda_config.0.create_auth_challenge等 10 个字段与 Lambda 资源的 ARN 相等并执行导入验证与更新验证这为示例的字段用法提供了测试背书。5.1 Lambda 函数本身的声明resource aws_lambda_function main { filename lambda_function.zip function_name terraform-example role aws_iam_role.main.arn handler exports.example runtime nodejs24.x }filename指向本地打包好的 lambda_function.zip示例目录中已附带handler为exports.example即 zip 内 JS 文件导出名为example的函数runtime为nodejs24.x以当前仓库示例为准不同版本的 Provider 支持的语言运行时集合可能不同。六、SMS 与邮件发送sms_configuration/email_configuration6.1 短信配置sms_configuration { external_id 12345 sns_caller_arn aws_iam_role.cidp.arn }源码 L539-563 规定external_id与sns_caller_arn均为必填sns_region可选默认跟随 Provider 区域可用verify.ValidRegionName校验。此处的external_id必须与 4.2 节信任策略中的sts:ExternalId完全一致。6.2 邮件配置email_configuration { reply_to_email_address foo.barbaz }源码 L199-207 对该字段做了正则校验必须匹配邮箱格式且email_sending_account默认COGNITO_DEFAULT即使用 Cognito 内置发件账户生产环境可改用DEVELOPER模式并配合from_email_address/source_arn使用 SES。七、标签与资源引用Terraform 声明式的闭环示例在用户池末尾声明了两枚标签tags { Name FooBar Project Terraform }aws_cognito_user_pool的 Schema 中tags与tags_all均由 internal/tags 包生成见 user_pool.go L585-586所有支持标签的 AWS 资源在 Provider 中遵循同一套标准tags声明、tags_all合并 Provider 默认标签后只读输出。整个示例的资源依赖关系可以概括为一条引用链aws_iam_role.main ── aws_lambda_function.main ── aws_cognito_user_pool.pool.lambda_config aws_iam_role.cidp ── aws_iam_role_policy.mainsns:publish ── aws_cognito_user_pool.pool.sms_configurationsns_caller_arn external_idTerraform 依据这些aws_xxx.xxx.attr表达式自动推导依赖拓扑apply时按序创建先 IAM 角色再 Lambda 函数最后用户池。八、从示例到生产的差异点提示基于源码约束示例中的几处写法在真实项目中需要调整互斥字段二选一email_verification_message与verification_message_template.0.email_message冲突源码 L246正式配置请统一使用verification_message_template块。Schema 约束要与业务匹配示例中 email 属性min_length 7 / max_length 15对真实邮箱过短建议放宽或删除required true的email属性在 Cognito 中本就默认必填。Lambda 触发器按需裁剪十个钩子指向同一函数适合演示生产上应拆分并配独立的执行角色与最小权限策略。短信区域与 SNS如需跨区域发送短信通过sms_configuration.sns_region显式指定 SNS 区域并确保对应区域存在可用主题/账号配额。删除保护源码中deletion_protection默认INACTIVEL151-156生产用户池建议显式开启ACTIVE以防误删。九、小结本示例以 5 个资源、3 个文件main.tf、variables.tf、lambda_function.zip完整演示了 Cognito User Pool 的 Terraform 落地路径通过 IAM 信任策略解决「Lambda 执行」与「Cognito 代发短信」两类授权通过lambda_config把用户生命周期钩子接入函数再以密码策略、Schema、消息模板与标签完成用户池的声明式配置。配合源码 internal/service/cognitoidp/user_pool.go 中的 Schema 约束与 user_pool_test.go 中的验收测试可以进一步验证任意字段的取值边界与行为作为自建身份体系的可靠起点。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考