Logto 集成 Vonage SMS 短信验证码登录从账号开通到源码级原理详解【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto导读本文围绕 Logto 官方提供的 Vonage SMS 短信连接器connector-vonage-sms展开完整讲解如何在 Vonage 平台开通短信能力、如何在 Logto 控制台配置 API Key / API Secret / Brand Name 与多场景短信模板并深入到该连接器的 TypeScript 源码与测试剖析短信发送的完整调用链、配置校验规则与模板回退机制。读完本文你将能够在自己的 Logto 实例中快速接入 Vonage 短信让终端用户通过短信验证码完成注册、登录、找回密码、MFA 校验等身份验证流程并具备自主排查配置问题的能力。Vonage SMS 连接器是什么Vonage 是一家全球性通信服务提供商提供包括短信SMS在内的云通信 API。Logto 团队在 packages/connectors/connector-vonage-sms 中维护了官方 Vonage SMS 连接器它是一个标准的 LogtoSmsConnector插件作用是让 Logto 的终端用户能够通过短信验证码完成注册Register与登录SignIn。从连接器的元数据可以看出见 constant.ts连接器 ID 与 target 均为vonage-sms类型为Sms短信类型连接器名称展示为 Vonage SMS Service描述为 Communications APIs to connect the world.在 Logto 控制台中以 JSON 表单formItems形式呈现配置项。第一步在 Vonage 侧完成前置准备提示如果你已经完成过 Vonage 账号配置可以直接跳过本节。要让该连接器正常工作首先需要拥有一个 Vonage 账号注册 Vonage 账号前往 Vonage 开发者平台注册账号这一步会为你发放一组 API Key 与 API Secret用于通过连接器访问 Vonage API。获取凭证登录 Vonage API DashboardAPI 控制台后在页面顶部即可看到你的 API Key 与 API Secret。租用虚拟号码Virtual Number短信发送需要一个发信号码你需要在 Vonage 号码管理页面租用一个虚拟号码否则无法向用户发送短信。此外短信的发送者身份Sender Identity即短信的from字段可以配置为自定义 Brand Name品牌名Vonage 对此有相应的合规要求配置前建议查阅官方关于自定义发送者 ID 的说明。需要说明的是以上为 Vonage 平台侧的运营操作Logto 仓库内并不包含这些外部步骤的具体实现账号、号码与凭证的最终获取结果以 Vonage 控制台为准。第二步在 Logto 控制台配置连接器完成 Vonage 侧准备后在 Logto 管理控制台启用 Vonage SMS 连接器并填写以下四个配置项与 constant.ts 中formItems的定义一一对应配置项字段 key类型必填说明API KeyapiKey文本Text是你的 Vonage API KeyAPI SecretapiSecret文本Text是你的 Vonage API SecretBrand NamebrandName文本Text是发送短信时使用的品牌名即短信的from字段Sender IdentityTemplatestemplatesJSONJson是各业务场景使用的短信模板数组可沿用默认值或按需修改其中brandName会被直接用作 Vonage 短信 API 的from字段因此它必须符合 Vonage 对发送者身份的规范例如使用已备案的品牌名或租用的号码否则短信可能被运营商拦截或发送失败。配置项的运行时校验规则连接器的配置在运行时由 zod schema 校验见 types.tsapiKey、apiSecret、brandName均为必填字符串templates是{ usageType: string; content: string }对象组成的数组校验器要求模板数组必须至少包含以下四种usageTypeRegister、SignIn、ForgotPassword、Generic缺一不可否则会抛出形如Template with UsageType (XXX) should be provided!的校验错误。也就是说即使你在控制台里删减了模板这四种核心场景的模板也必须是完整存在的。第三步理解模板系统与 usageType模板是短信内容的来源每个模板由usageType使用场景和content短信正文构成。该连接器的默认配置内置了9 个场景的模板见 constant.ts 的defaultValueusageType默认短信内容SignInYour Logto sign-in verification code is{{code}}. The code will remain active for 10 minutes.RegisterYour Logto sign-up verification code is{{code}}. The code will remain active for 10 minutes.ForgotPasswordYour Logto password change verification code is{{code}}. The code will remain active for 10 minutes.OrganizationInvitationYour Logto organization invitation code is{{code}}. The code will remain active for 10 minutes.GenericYour Logto verification code is{{code}}. The code will remain active for 10 minutes.UserPermissionValidationYour Logto permission validation code is{{code}}. The code will remain active for 10 minutes.BindNewIdentifierYour Logto new identifier binding code is{{code}}. The code will remain active for 10 minutes.MfaVerificationYour Logto MFA verification code is{{code}}. The code will remain active for 10 minutes.BindMfaYour Logto 2-step verification setup code is{{code}}. The code will remain active for 10 minutes.以上 9 种场景覆盖了 Logto 中短信验证码的所有典型用途注册、登录、找回密码、组织邀请、通用验证、权限验证、绑定新标识、MFA 验证与 MFA 绑定。你可以直接沿用默认模板也可以根据业务需要修改文案例如替换品牌语气、调整有效期提示。模板占位符{{code}}是如何被替换的模板正文中的{{code}}不是简单字符串拼接而是由 connector-kit 提供的replaceSendMessageHandlebars函数在运行时完成替换见 packages/toolkit/connector-kit/src/index.ts使用正则/{{\s*([\w.])\s*}}/g匹配所有{{变量}}占位符支持点号路径如{{application.name}}从发送负载payload中按路径取值若负载中不存在对应根变量则原样保留该占位符若值为空则替换为空字符串。因此短信内容的最终形态由所选模板 本次发送负载共同决定验证码{{code}}即来自 Logto 生成的验证码负载。模板回退机制在发送时连接器通过getConfigTemplateByType(type, config)按当前业务类型如SignIn查找模板如果找不到对应场景的模板会自动回退到Generic通用模板见 packages/toolkit/connector-kit/src/index.ts。这一行为在 CHANGELOG 中也有记录版本 0.2.1 引入了当找不到特定场景模板时回退到TemplateType.Generic的逻辑。这解释了为什么配置文件里Generic模板几乎是保底的存在——即使新增了未配置模板的新业务场景短信也能通过通用模板正常发出。第四步源码级解析——短信发送的完整调用链连接器的核心实现在 index.ts整体结构非常清晰createVonageSmsConnector工厂函数创建一个标准的SmsConnector对象包含元数据、类型、配置校验器configGuard与sendMessage发送函数。一次短信发送的调用链如下Logto 认证流程注册/登录/找回密码等 └─ sendMessage({ to, type, payload }, inputConfig) ├─ 1. 读取配置inputConfig ?? getConfig(vonage-sms) ├─ 2. validateConfig(config, vonageSmsConfigGuard) // zod 校验 ├─ 3. getConfigTemplateByType(type, config) // 取模板缺省回退 Generic ├─ 4. new Auth({ apiKey, apiSecret }) // vonage/auth 构造凭证 ├─ 5. new Vonage(vonageAuth) // vonage/server-sdk 初始化客户端 ├─ 6. vonage.sms.send({ from: brandName, to, text }) // 发送短信 └─ 7. 失败时包装为 ConnectorError(General) 抛出几个关键实现细节值得注意配置来源sendMessage支持通过inputConfig直接注入配置便于测试与上层复用否则回退到从 Logto 数据库按defaultMetadata.id即vonage-sms读取已保存的连接器配置。SDK 依赖连接器基于官方vonage/auth^1.12.0与vonage/server-sdk^3.19.0实现见 package.json包版本为 0.2.5运行环境要求 Node.js ^22.14.0。错误处理发送过程中任何异常都会被捕获若为Error实例则包装成ConnectorError错误码General附带原始错误信息重新抛出保证上层拿到的是 Logto 统一的连接器错误结构便于在认证流程中做统一的错误提示与日志记录。模板缺失保护assert(template, ...)确保取不到模板时直接抛出TemplateNotFound类型的ConnectorError正常情况下因存在Generic回退极少触发。第五步单元测试与可验证性连接器自带基于 Vitest 的单元测试 index.test.ts通过 mock 的getConfig返回 mock.ts 中预置的配置含api-key、api-secret、brand name及一个Generic模板验证createConnector({ getConfig })能够无异常初始化init without throwing errors从侧面印证了配置结构与连接器工厂的合法性。运行方式cd packages/connectors/connector-vonage-sms pnpm test # 执行 vitest run src pnpm check # 执行 tsc --noEmit 类型检查常见问题与排查建议校验报错Template with UsageType (XXX) should be provided!说明templates数组中缺少Register/SignIn/ForgotPassword/Generic中的某一项回到控制台补全即可。短信发送失败优先核对apiKey/apiSecret是否正确、Brand Name 是否符合 Vonage 发送者身份规范、是否已租用有效虚拟号码连接器会以ConnectorError(General)携带底层 SDK 的原始错误信息可从服务端日志中定位具体原因。模板文案中需要更多动态内容{{code}}之外还支持点号路径变量如{{user.name}}只要负载中存在对应字段即可被替换。新增业务场景无专属模板无需担心连接器会自动回退到Generic模板保证短信仍能发出。小结Vonage SMS 连接器是 Logto 官方短信连接器体系中的一员其价值在于以极低的接入成本为 SaaS 与 AI 应用补齐短信验证码这一身份验证通道。从配置上看它只需要 API Key、API Secret、Brand Name 与模板数组四个要素从实现上看它通过 zod 配置校验、usageType 模板选择、Generic 回退、Handlebars 占位符替换与官方 SDK 封装构成了一个健壮且可测试的短信发送链路。如果你想在自己的 Logto 实例中快速验证短信登录能力可以直接参考 connector-vonage-sms 目录下的 README.md、index.ts 与 types.ts 展开实践。【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Logto 集成 Vonage SMS 短信验证码登录：从账号开通到源码级原理详解
Logto 集成 Vonage SMS 短信验证码登录从账号开通到源码级原理详解【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto导读本文围绕 Logto 官方提供的 Vonage SMS 短信连接器connector-vonage-sms展开完整讲解如何在 Vonage 平台开通短信能力、如何在 Logto 控制台配置 API Key / API Secret / Brand Name 与多场景短信模板并深入到该连接器的 TypeScript 源码与测试剖析短信发送的完整调用链、配置校验规则与模板回退机制。读完本文你将能够在自己的 Logto 实例中快速接入 Vonage 短信让终端用户通过短信验证码完成注册、登录、找回密码、MFA 校验等身份验证流程并具备自主排查配置问题的能力。Vonage SMS 连接器是什么Vonage 是一家全球性通信服务提供商提供包括短信SMS在内的云通信 API。Logto 团队在 packages/connectors/connector-vonage-sms 中维护了官方 Vonage SMS 连接器它是一个标准的 LogtoSmsConnector插件作用是让 Logto 的终端用户能够通过短信验证码完成注册Register与登录SignIn。从连接器的元数据可以看出见 constant.ts连接器 ID 与 target 均为vonage-sms类型为Sms短信类型连接器名称展示为 Vonage SMS Service描述为 Communications APIs to connect the world.在 Logto 控制台中以 JSON 表单formItems形式呈现配置项。第一步在 Vonage 侧完成前置准备提示如果你已经完成过 Vonage 账号配置可以直接跳过本节。要让该连接器正常工作首先需要拥有一个 Vonage 账号注册 Vonage 账号前往 Vonage 开发者平台注册账号这一步会为你发放一组 API Key 与 API Secret用于通过连接器访问 Vonage API。获取凭证登录 Vonage API DashboardAPI 控制台后在页面顶部即可看到你的 API Key 与 API Secret。租用虚拟号码Virtual Number短信发送需要一个发信号码你需要在 Vonage 号码管理页面租用一个虚拟号码否则无法向用户发送短信。此外短信的发送者身份Sender Identity即短信的from字段可以配置为自定义 Brand Name品牌名Vonage 对此有相应的合规要求配置前建议查阅官方关于自定义发送者 ID 的说明。需要说明的是以上为 Vonage 平台侧的运营操作Logto 仓库内并不包含这些外部步骤的具体实现账号、号码与凭证的最终获取结果以 Vonage 控制台为准。第二步在 Logto 控制台配置连接器完成 Vonage 侧准备后在 Logto 管理控制台启用 Vonage SMS 连接器并填写以下四个配置项与 constant.ts 中formItems的定义一一对应配置项字段 key类型必填说明API KeyapiKey文本Text是你的 Vonage API KeyAPI SecretapiSecret文本Text是你的 Vonage API SecretBrand NamebrandName文本Text是发送短信时使用的品牌名即短信的from字段Sender IdentityTemplatestemplatesJSONJson是各业务场景使用的短信模板数组可沿用默认值或按需修改其中brandName会被直接用作 Vonage 短信 API 的from字段因此它必须符合 Vonage 对发送者身份的规范例如使用已备案的品牌名或租用的号码否则短信可能被运营商拦截或发送失败。配置项的运行时校验规则连接器的配置在运行时由 zod schema 校验见 types.tsapiKey、apiSecret、brandName均为必填字符串templates是{ usageType: string; content: string }对象组成的数组校验器要求模板数组必须至少包含以下四种usageTypeRegister、SignIn、ForgotPassword、Generic缺一不可否则会抛出形如Template with UsageType (XXX) should be provided!的校验错误。也就是说即使你在控制台里删减了模板这四种核心场景的模板也必须是完整存在的。第三步理解模板系统与 usageType模板是短信内容的来源每个模板由usageType使用场景和content短信正文构成。该连接器的默认配置内置了9 个场景的模板见 constant.ts 的defaultValueusageType默认短信内容SignInYour Logto sign-in verification code is{{code}}. The code will remain active for 10 minutes.RegisterYour Logto sign-up verification code is{{code}}. The code will remain active for 10 minutes.ForgotPasswordYour Logto password change verification code is{{code}}. The code will remain active for 10 minutes.OrganizationInvitationYour Logto organization invitation code is{{code}}. The code will remain active for 10 minutes.GenericYour Logto verification code is{{code}}. The code will remain active for 10 minutes.UserPermissionValidationYour Logto permission validation code is{{code}}. The code will remain active for 10 minutes.BindNewIdentifierYour Logto new identifier binding code is{{code}}. The code will remain active for 10 minutes.MfaVerificationYour Logto MFA verification code is{{code}}. The code will remain active for 10 minutes.BindMfaYour Logto 2-step verification setup code is{{code}}. The code will remain active for 10 minutes.以上 9 种场景覆盖了 Logto 中短信验证码的所有典型用途注册、登录、找回密码、组织邀请、通用验证、权限验证、绑定新标识、MFA 验证与 MFA 绑定。你可以直接沿用默认模板也可以根据业务需要修改文案例如替换品牌语气、调整有效期提示。模板占位符{{code}}是如何被替换的模板正文中的{{code}}不是简单字符串拼接而是由 connector-kit 提供的replaceSendMessageHandlebars函数在运行时完成替换见 packages/toolkit/connector-kit/src/index.ts使用正则/{{\s*([\w.])\s*}}/g匹配所有{{变量}}占位符支持点号路径如{{application.name}}从发送负载payload中按路径取值若负载中不存在对应根变量则原样保留该占位符若值为空则替换为空字符串。因此短信内容的最终形态由所选模板 本次发送负载共同决定验证码{{code}}即来自 Logto 生成的验证码负载。模板回退机制在发送时连接器通过getConfigTemplateByType(type, config)按当前业务类型如SignIn查找模板如果找不到对应场景的模板会自动回退到Generic通用模板见 packages/toolkit/connector-kit/src/index.ts。这一行为在 CHANGELOG 中也有记录版本 0.2.1 引入了当找不到特定场景模板时回退到TemplateType.Generic的逻辑。这解释了为什么配置文件里Generic模板几乎是保底的存在——即使新增了未配置模板的新业务场景短信也能通过通用模板正常发出。第四步源码级解析——短信发送的完整调用链连接器的核心实现在 index.ts整体结构非常清晰createVonageSmsConnector工厂函数创建一个标准的SmsConnector对象包含元数据、类型、配置校验器configGuard与sendMessage发送函数。一次短信发送的调用链如下Logto 认证流程注册/登录/找回密码等 └─ sendMessage({ to, type, payload }, inputConfig) ├─ 1. 读取配置inputConfig ?? getConfig(vonage-sms) ├─ 2. validateConfig(config, vonageSmsConfigGuard) // zod 校验 ├─ 3. getConfigTemplateByType(type, config) // 取模板缺省回退 Generic ├─ 4. new Auth({ apiKey, apiSecret }) // vonage/auth 构造凭证 ├─ 5. new Vonage(vonageAuth) // vonage/server-sdk 初始化客户端 ├─ 6. vonage.sms.send({ from: brandName, to, text }) // 发送短信 └─ 7. 失败时包装为 ConnectorError(General) 抛出几个关键实现细节值得注意配置来源sendMessage支持通过inputConfig直接注入配置便于测试与上层复用否则回退到从 Logto 数据库按defaultMetadata.id即vonage-sms读取已保存的连接器配置。SDK 依赖连接器基于官方vonage/auth^1.12.0与vonage/server-sdk^3.19.0实现见 package.json包版本为 0.2.5运行环境要求 Node.js ^22.14.0。错误处理发送过程中任何异常都会被捕获若为Error实例则包装成ConnectorError错误码General附带原始错误信息重新抛出保证上层拿到的是 Logto 统一的连接器错误结构便于在认证流程中做统一的错误提示与日志记录。模板缺失保护assert(template, ...)确保取不到模板时直接抛出TemplateNotFound类型的ConnectorError正常情况下因存在Generic回退极少触发。第五步单元测试与可验证性连接器自带基于 Vitest 的单元测试 index.test.ts通过 mock 的getConfig返回 mock.ts 中预置的配置含api-key、api-secret、brand name及一个Generic模板验证createConnector({ getConfig })能够无异常初始化init without throwing errors从侧面印证了配置结构与连接器工厂的合法性。运行方式cd packages/connectors/connector-vonage-sms pnpm test # 执行 vitest run src pnpm check # 执行 tsc --noEmit 类型检查常见问题与排查建议校验报错Template with UsageType (XXX) should be provided!说明templates数组中缺少Register/SignIn/ForgotPassword/Generic中的某一项回到控制台补全即可。短信发送失败优先核对apiKey/apiSecret是否正确、Brand Name 是否符合 Vonage 发送者身份规范、是否已租用有效虚拟号码连接器会以ConnectorError(General)携带底层 SDK 的原始错误信息可从服务端日志中定位具体原因。模板文案中需要更多动态内容{{code}}之外还支持点号路径变量如{{user.name}}只要负载中存在对应字段即可被替换。新增业务场景无专属模板无需担心连接器会自动回退到Generic模板保证短信仍能发出。小结Vonage SMS 连接器是 Logto 官方短信连接器体系中的一员其价值在于以极低的接入成本为 SaaS 与 AI 应用补齐短信验证码这一身份验证通道。从配置上看它只需要 API Key、API Secret、Brand Name 与模板数组四个要素从实现上看它通过 zod 配置校验、usageType 模板选择、Generic 回退、Handlebars 占位符替换与官方 SDK 封装构成了一个健壮且可测试的短信发送链路。如果你想在自己的 Logto 实例中快速验证短信登录能力可以直接参考 connector-vonage-sms 目录下的 README.md、index.ts 与 types.ts 展开实践。【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考