尧图网站建设 
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 官方 SMS 连接器之一——Vonage SMSlogto/connector-vonage-sms展开讲解如何在 Logto 中启用 Vonage 短信服务让终端用户通过短信验证码完成注册与登录并深入源码分析该连接器的配置校验、模板匹配与消息发送的底层实现。读完本文你将掌握在 Vonage 开发者平台完成账号与号码准备、在 Logto 控制台填写四项关键配置API Key、API Secret、Brand Name、Templates、理解模板usageType与默认文案占位符{{code}}的机制以及发送链路如何与logto/connector-kit协同工作。一、Vonage SMS 连接器是什么Vonage 是全球性的通信服务提供商提供基于云的消息服务其中就包括 SMS短消息服务。Logto 团队为 Vonage 提供了官方连接器 connector-vonage-sms其核心作用是让 Logto 终端用户可以通过手机短信验证码完成注册和登录即 passwordless 无密码认证这也是 Logto 支持短信验证码登录的多种渠道之一。从该连接器的 package.json 可以看到它的定位与依赖包名logto/connector-vonage-sms当前版本0.2.5核心运行时依赖vonage/auth认证、vonage/server-sdk发送短信、zod配置校验、logto/connector-kit连接器开发套件运行环境要求 Node.js^22.14.0。连接器在 constant.ts 中定义了自己的元信息defaultMetadataid 为vonage-sms类型为ConnectorType.Sms并声明了四个表单配置项这些配置项会直接渲染在 Logto 管理控制台的连接器配置页面上。二、在 Vonage 平台侧的准备如果你已经完成过 Vonage 的相关配置可以跳过本小节。要使用该连接器需要先在 Vonage 注册账号。注册完成后可以在Vonage API Dashboard顶部找到两个关键凭证API Key访问 Vonage API 时使用的密钥标识API Secret与 API Key 配套的密钥。此外为了真正发送短信通常还需要租用rent一个虚拟号码virtual number短信将以该号码作为发送方。关于号码管理、自定义发送方 IDCustom Sender ID以及 SMS API 的更多细节可以参阅 Vonage 官方文档中的账号管理、号码管理与 SMS 概览章节README 中已给出相关指引。三、在 Logto 中配置连接器在 Logto 管理控制台中安装logto/connector-vonage-sms后需要填写以下配置项与 constant.ts 中formItems定义一一对应配置项必填说明API Key是你的 Vonage API KeyAPI Secret是你的 Vonage API SecretBrand Name是发送短信时使用的品牌名即 Vonage 消息中的from字段可参考 Vonage 自定义发送方 ID 文档Templates是用于发送短信的模板可以使用默认模板也可按需修改3.1 默认模板与 usageTypeTemplates 是一个 JSON 数组每项包含usageType使用场景与content短信文案两个字段。连接器在 constant.ts 中提供了完整的默认模板覆盖了 Logto 短信验证码的全部业务场景usageType默认文案contentSignInYour 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 个场景是默认值并不是硬性约束。真正被配置校验强制要求的只有 4 个基础场景详见下文“配置校验与源码实现”。{{code}}是占位符发送时会由实际验证码替换你也可以在文案中加入其他 payload 字段例如{{application.name}}只要 payload 中存在对应键即可。3.2 配置的运行时校验types.ts 使用 zod 定义了配置守卫vonageSmsConfigGuardapiKey、apiSecret、brandName均为必填字符串templates为对象数组每个对象必须有usageType与content两个字符串字段模板数组必须至少包含Register、SignIn、ForgotPassword、Generic四种 usageType否则会在校验时报错错误信息会列出缺失的类型。这一约束确保了无论何种触发场景连接器都能找到可用的模板不会出现“无模板可发”的运行期错误。四、发送短信的源码级实现连接器的核心逻辑集中在 index.ts 中它导出一个符合 Logto 连接器契约的工厂函数createVonageSmsConnector返回对象包含metadata来自defaultMetadatatypeConnectorType.SmsconfigGuardvonageSmsConfigGuardsendMessage实际的发送函数。4.1 发送主流程sendMessage的执行步骤如下读取配置从data中解构出to目标手机号、type模板类型与payload消息载荷配置优先使用inputConfig否则通过getConfig(defaultMetadata.id)从数据库读取校验配置调用validateConfig(config, vonageSmsConfigGuard)不合法则直接抛错选择模板调用getConfigTemplateByType(type, config)按场景挑选模板找不到时抛出TemplateNotFound错误渲染文案用replaceSendMessageHandlebars(template.content, payload)替换占位符调用 Vonage SDK使用new Auth({ apiKey, apiSecret })构造认证再通过new Vonage(vonageAuth)实例调用vonage.sms.send({ from: brandName, to, text })发送短信异常包装发送失败时将Error包装为ConnectorError(ConnectorErrorCodes.General, error.message)向上抛出。4.2 模板匹配的兜底逻辑模板选择函数 getConfigTemplateByType 定义在logto/connector-kit中逻辑如下先按传入的type精确匹配templates中的usageType若未命中则回退到TemplateType.Generic即兜底使用Generic模板。这正是 CHANGELOG 中0.2.1版本记录的那条变更“fall back toTemplateType.Genericif a usage-specific template is not found”找不到特定场景模板时回退到通用模板。因此即便你只配置了 4 个必填场景而缺少某个可选场景如MfaVerification连接器也能用Generic文案完成发送不会中断流程。4.3 占位符渲染机制replaceSendMessageHandlebars 是占位符渲染的实现它用正则/{{\s*([\w.])\s*}}/g匹配{{key}}或{{key.subKey}}形式的占位符若 payload 中不存在该根键则保留原占位符原样输出存在则通过getValue按点号路径取值并转为字符串。这解释了默认模板中{{code}}会被替换成真实验证码的原理也说明你在自定义模板时可以引用 payload 中更深的嵌套字段。4.4 测试与运行方式该连接器的单元测试位于 index.test.ts配合 mock.ts 提供的模拟配置含Generic模板验证了连接器“以合法配置初始化时不抛错”这一基础契约。在仓库中可这样运行测试与构建# 在连接器目录下运行 pnpm test # vitest 执行 src 下单元测试 pnpm build # tsup 构建产物到 lib/ pnpm check # tsc --noEmit 类型检查 pnpm lint # eslint 检查 src五、与其他 SMS 连接器的关系Logto 的 SMS 连接器遵循同一套logto/connector-kit契约CreateConnectorSmsConnectorSendMessageFunction因此 Vonage SMS 与仓库中的阿里云短信、腾讯云短信、Twilio、SendGrid 等连接器在 Logto 内的接入与使用方式保持一致都是通过type: ConnectorType.Sms注册为短信渠道由 Logto 核心在需要发送验证码时统一调用sendMessage。区别仅在于各家云厂商的凭证体系与 API 封装Vonage 使用vonage/server-sdk以及各自的默认模板文案。如果你所在地区或团队已经使用 Vonage那么这个连接器可以直接复用 Logto 现有的短信验证码注册、登录、找回密码、MFA 与组织邀请等完整流程无需改动上层业务代码。六、常见问题与排错思路配置保存失败提示缺少某 usageType 模板vonageSmsConfigGuard强制要求Register、SignIn、ForgotPassword、Generic四个场景请在 Templates 中补全后再保存。登录时提示找不到模板TemplateNotFound确认触发的场景类型在模板中存在若仅缺少可选场景getConfigTemplateByType会自动回退到Generic可检查Generic模板是否已配置。短信发送失败优先核对 API Key / API Secret 是否正确、虚拟号码是否已租用、Brand Namefrom字段是否符合 Vonage 对自定义发送方 ID 的要求连接器会把底层 SDK 的Error.message包装成ConnectorError(General, ...)抛出可在 Logto 日志中查看具体原因。自定义模板不生效注意模板字段名必须是usageType与content且content中的占位符要写成{{code}}形式支持{{a.b}}嵌套路径payload 中不存在的键会保留原样输出不会报错。七、版本演进脉络从 CHANGELOG.md 可以梳理该连接器的演进轨迹这有助于判断你所用版本的特性边界0.0.1随安全更新升级依赖logto/connector-kit4.1.10.1.0Node 版本要求提升至^22.14.0与logto/connector-kit4.3.0同步0.2.0为模板默认值补齐全部 usageType即上文 9 个默认场景来自变更add full usage types to templates default value0.2.1新增按场景找不到模板时回退TemplateType.Generic的兜底逻辑0.2.2~0.2.5跟随logto/connector-kit升级5.x 系列均为依赖性变更无行为改动。也就是说若你希望体验完整的默认模板与 Generic 兜底能力建议使用0.2.1及以上版本当前仓库中的版本为0.2.5。结语Vonage SMS 连接器是 Logto 短信验证码体系中的一个典型实现配置层用 zod 严格把关、模板层用 usageType Generic 兜底保证可用性、发送层用vonage/server-sdk完成真实投递且全程复用logto/connector-kit的标准契约。如果你正在为 Logto 用户接入短信验证码参考本文的顺序完成 Vonage 平台准备与 Logto 配置即可快速上线若需深度定制建议继续阅读 connector-kit 源码 中的模板与占位符实现理解其设计边界后再做扩展。【免费下载链接】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 官方 SMS 连接器之一——Vonage SMSlogto/connector-vonage-sms展开讲解如何在 Logto 中启用 Vonage 短信服务让终端用户通过短信验证码完成注册与登录并深入源码分析该连接器的配置校验、模板匹配与消息发送的底层实现。读完本文你将掌握在 Vonage 开发者平台完成账号与号码准备、在 Logto 控制台填写四项关键配置API Key、API Secret、Brand Name、Templates、理解模板usageType与默认文案占位符{{code}}的机制以及发送链路如何与logto/connector-kit协同工作。一、Vonage SMS 连接器是什么Vonage 是全球性的通信服务提供商提供基于云的消息服务其中就包括 SMS短消息服务。Logto 团队为 Vonage 提供了官方连接器 connector-vonage-sms其核心作用是让 Logto 终端用户可以通过手机短信验证码完成注册和登录即 passwordless 无密码认证这也是 Logto 支持短信验证码登录的多种渠道之一。从该连接器的 package.json 可以看到它的定位与依赖包名logto/connector-vonage-sms当前版本0.2.5核心运行时依赖vonage/auth认证、vonage/server-sdk发送短信、zod配置校验、logto/connector-kit连接器开发套件运行环境要求 Node.js^22.14.0。连接器在 constant.ts 中定义了自己的元信息defaultMetadataid 为vonage-sms类型为ConnectorType.Sms并声明了四个表单配置项这些配置项会直接渲染在 Logto 管理控制台的连接器配置页面上。二、在 Vonage 平台侧的准备如果你已经完成过 Vonage 的相关配置可以跳过本小节。要使用该连接器需要先在 Vonage 注册账号。注册完成后可以在Vonage API Dashboard顶部找到两个关键凭证API Key访问 Vonage API 时使用的密钥标识API Secret与 API Key 配套的密钥。此外为了真正发送短信通常还需要租用rent一个虚拟号码virtual number短信将以该号码作为发送方。关于号码管理、自定义发送方 IDCustom Sender ID以及 SMS API 的更多细节可以参阅 Vonage 官方文档中的账号管理、号码管理与 SMS 概览章节README 中已给出相关指引。三、在 Logto 中配置连接器在 Logto 管理控制台中安装logto/connector-vonage-sms后需要填写以下配置项与 constant.ts 中formItems定义一一对应配置项必填说明API Key是你的 Vonage API KeyAPI Secret是你的 Vonage API SecretBrand Name是发送短信时使用的品牌名即 Vonage 消息中的from字段可参考 Vonage 自定义发送方 ID 文档Templates是用于发送短信的模板可以使用默认模板也可按需修改3.1 默认模板与 usageTypeTemplates 是一个 JSON 数组每项包含usageType使用场景与content短信文案两个字段。连接器在 constant.ts 中提供了完整的默认模板覆盖了 Logto 短信验证码的全部业务场景usageType默认文案contentSignInYour 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 个场景是默认值并不是硬性约束。真正被配置校验强制要求的只有 4 个基础场景详见下文“配置校验与源码实现”。{{code}}是占位符发送时会由实际验证码替换你也可以在文案中加入其他 payload 字段例如{{application.name}}只要 payload 中存在对应键即可。3.2 配置的运行时校验types.ts 使用 zod 定义了配置守卫vonageSmsConfigGuardapiKey、apiSecret、brandName均为必填字符串templates为对象数组每个对象必须有usageType与content两个字符串字段模板数组必须至少包含Register、SignIn、ForgotPassword、Generic四种 usageType否则会在校验时报错错误信息会列出缺失的类型。这一约束确保了无论何种触发场景连接器都能找到可用的模板不会出现“无模板可发”的运行期错误。四、发送短信的源码级实现连接器的核心逻辑集中在 index.ts 中它导出一个符合 Logto 连接器契约的工厂函数createVonageSmsConnector返回对象包含metadata来自defaultMetadatatypeConnectorType.SmsconfigGuardvonageSmsConfigGuardsendMessage实际的发送函数。4.1 发送主流程sendMessage的执行步骤如下读取配置从data中解构出to目标手机号、type模板类型与payload消息载荷配置优先使用inputConfig否则通过getConfig(defaultMetadata.id)从数据库读取校验配置调用validateConfig(config, vonageSmsConfigGuard)不合法则直接抛错选择模板调用getConfigTemplateByType(type, config)按场景挑选模板找不到时抛出TemplateNotFound错误渲染文案用replaceSendMessageHandlebars(template.content, payload)替换占位符调用 Vonage SDK使用new Auth({ apiKey, apiSecret })构造认证再通过new Vonage(vonageAuth)实例调用vonage.sms.send({ from: brandName, to, text })发送短信异常包装发送失败时将Error包装为ConnectorError(ConnectorErrorCodes.General, error.message)向上抛出。4.2 模板匹配的兜底逻辑模板选择函数 getConfigTemplateByType 定义在logto/connector-kit中逻辑如下先按传入的type精确匹配templates中的usageType若未命中则回退到TemplateType.Generic即兜底使用Generic模板。这正是 CHANGELOG 中0.2.1版本记录的那条变更“fall back toTemplateType.Genericif a usage-specific template is not found”找不到特定场景模板时回退到通用模板。因此即便你只配置了 4 个必填场景而缺少某个可选场景如MfaVerification连接器也能用Generic文案完成发送不会中断流程。4.3 占位符渲染机制replaceSendMessageHandlebars 是占位符渲染的实现它用正则/{{\s*([\w.])\s*}}/g匹配{{key}}或{{key.subKey}}形式的占位符若 payload 中不存在该根键则保留原占位符原样输出存在则通过getValue按点号路径取值并转为字符串。这解释了默认模板中{{code}}会被替换成真实验证码的原理也说明你在自定义模板时可以引用 payload 中更深的嵌套字段。4.4 测试与运行方式该连接器的单元测试位于 index.test.ts配合 mock.ts 提供的模拟配置含Generic模板验证了连接器“以合法配置初始化时不抛错”这一基础契约。在仓库中可这样运行测试与构建# 在连接器目录下运行 pnpm test # vitest 执行 src 下单元测试 pnpm build # tsup 构建产物到 lib/ pnpm check # tsc --noEmit 类型检查 pnpm lint # eslint 检查 src五、与其他 SMS 连接器的关系Logto 的 SMS 连接器遵循同一套logto/connector-kit契约CreateConnectorSmsConnectorSendMessageFunction因此 Vonage SMS 与仓库中的阿里云短信、腾讯云短信、Twilio、SendGrid 等连接器在 Logto 内的接入与使用方式保持一致都是通过type: ConnectorType.Sms注册为短信渠道由 Logto 核心在需要发送验证码时统一调用sendMessage。区别仅在于各家云厂商的凭证体系与 API 封装Vonage 使用vonage/server-sdk以及各自的默认模板文案。如果你所在地区或团队已经使用 Vonage那么这个连接器可以直接复用 Logto 现有的短信验证码注册、登录、找回密码、MFA 与组织邀请等完整流程无需改动上层业务代码。六、常见问题与排错思路配置保存失败提示缺少某 usageType 模板vonageSmsConfigGuard强制要求Register、SignIn、ForgotPassword、Generic四个场景请在 Templates 中补全后再保存。登录时提示找不到模板TemplateNotFound确认触发的场景类型在模板中存在若仅缺少可选场景getConfigTemplateByType会自动回退到Generic可检查Generic模板是否已配置。短信发送失败优先核对 API Key / API Secret 是否正确、虚拟号码是否已租用、Brand Namefrom字段是否符合 Vonage 对自定义发送方 ID 的要求连接器会把底层 SDK 的Error.message包装成ConnectorError(General, ...)抛出可在 Logto 日志中查看具体原因。自定义模板不生效注意模板字段名必须是usageType与content且content中的占位符要写成{{code}}形式支持{{a.b}}嵌套路径payload 中不存在的键会保留原样输出不会报错。七、版本演进脉络从 CHANGELOG.md 可以梳理该连接器的演进轨迹这有助于判断你所用版本的特性边界0.0.1随安全更新升级依赖logto/connector-kit4.1.10.1.0Node 版本要求提升至^22.14.0与logto/connector-kit4.3.0同步0.2.0为模板默认值补齐全部 usageType即上文 9 个默认场景来自变更add full usage types to templates default value0.2.1新增按场景找不到模板时回退TemplateType.Generic的兜底逻辑0.2.2~0.2.5跟随logto/connector-kit升级5.x 系列均为依赖性变更无行为改动。也就是说若你希望体验完整的默认模板与 Generic 兜底能力建议使用0.2.1及以上版本当前仓库中的版本为0.2.5。结语Vonage SMS 连接器是 Logto 短信验证码体系中的一个典型实现配置层用 zod 严格把关、模板层用 usageType Generic 兜底保证可用性、发送层用vonage/server-sdk完成真实投递且全程复用logto/connector-kit的标准契约。如果你正在为 Logto 用户接入短信验证码参考本文的顺序完成 Vonage 平台准备与 Logto 配置即可快速上线若需深度定制建议继续阅读 connector-kit 源码 中的模板与占位符实现理解其设计边界后再做扩展。【免费下载链接】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），仅供参考