Logto 短信宝短信连接器接入指南短信验证码登录、注册与模板配置实战【免费下载链接】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 开源身份认证基础设施中的官方短信连接器——短信宝SMSBao短信服务展开完整讲解从短信宝平台侧的账号与凭证准备、模板审核到 Logto 管理控制台内的连接器配置、模板映射再到底层发送流程与错误码处理的全部环节。读完本文你将掌握如何在 Logto 中启用短信验证码登录、注册、重置密码等验证流程并理解该连接器在 index.ts 中真实请求构造与错误处理的实现原理。连接器是什么Logto 与短信宝的对接桥短信宝SMSBao是国内一家短信服务提供商。Logto 的短信宝短信连接器connector-smsbao-sms是该项目的官方连接器它的职责是将 Logto 的「发送验证码」事件翻译成对短信宝国内短信 API 的调用让终端用户通过手机短信验证码完成登录SignIn、注册Register、重置密码ForgotPassword以及 MFA 验证、绑定新标识等各类验证流程。从源码结构看该连接器属于标准的 Logto SMS 类型连接器导出createSmsbaoSmsConnector声明type: ConnectorType.Sms并通过sendMessage函数与 Logto 核心交互见 index.ts。整个包体积精简依赖logto/connector-kit、got与zod见 package.json。需要特别说明的是该连接器仅支持短信宝的国内短信发送余额查询、上行短信推送、国际短信和语音验证码等 API 均不在其功能范围内。第一步在短信宝平台完成配置在使用 Logto 之前需要先到短信宝完成账号与模板准备。此步骤全部在短信宝侧完成Logto 仅消费其凭证。1.1 创建短信宝账号访问短信宝官网注册账号并完成短信服务所需的账号配置包括必要的实名认证与签名/模板申请流程。1.2 获取连接凭证在短信宝后台准备以下三项配置信息配置项是否必填说明用户名username必填短信宝账号的用户名API Key 或 MD5 密码passwordOrApiKey必填推荐使用短信宝 API Key也可以使用短信宝登录密码的 MD5 值产品 IDgoodsId可选仅在使用短信宝专用通道产品时填写一个值得注意的实现细节是连接器会原样发送 API Key 或 MD5 密码不会在 Logto 中再次哈希。也就是说如果填入 MD5 密码请确保传入的就是已完成 MD5 运算后的值如果填入 API Key同样按原值提交。这一点在 index.ts 中可见u: username, p: passwordOrApiKey直接作为查询参数发出不做任何二次处理。1.3 配置并审核短信模板在短信宝后台创建短信模板并等待审核通过后再启用连接器。Logto 中配置的模板内容应与短信宝审核通过的内容保持一致并使用{{code}}这类 Logto 占位符标记验证码插入位置。第二步在 Logto 管理控制台中启用连接器在短信宝侧准备就绪后按以下步骤在 Logto 中完成配置进入 Logto 管理控制台打开「连接器」页面找到并点击「短信宝短信服务」对应元数据中的SMSBao SMS Service见 constant.ts在配置表单中依次填入用户名短信宝用户名API Key 或 MD5 密码短信宝 API Key 或已做 MD5 的密码产品 ID可选的专用通道产品 ID短信模板按 Logto 用途类型配置对应模板内容。保存后即可在登录、注册等体验配置中将该短信通道指定为验证码发送渠道。配置字段与模板结构深度解析控制台中的表单字段并非写死在页面里而是由连接器通过metadata.formItems声明的见 constant.ts。理解这套声明有助于把握每个字段的校验规则与默认值。3.1 连接器配置表单字段表单字段类型必填是否机密默认值/占位提示username文本是否usernamepasswordOrApiKey文本是是机密字段api-key-or-md5-passwordgoodsId文本否否product-idtemplatesJSON是否内置 9 类默认模板内容均为「您的验证码是 {{code}}。如非本人操作请忽略本短信」其中passwordOrApiKey被标记为机密字段isConfidential: true在管理控制台中会被加密存储避免凭证明文暴露。3.2 配置的运行时校验规则提交后的配置会经过smsbaoSmsConfigGuardzod schema校验只有通过校验的连接器才能正常工作见 types.tsconst smsbaoSmsConfigGuard z.object({ username: z.string().min(1), passwordOrApiKey: z.string().min(1), goodsId: z.string().min(1).optional(), templates: z.array(templateGuard).min(1), });即username、passwordOrApiKey均不可为空字符串goodsId可选一旦填写至少 1 个字符templates至少需要配置 1 条模板。每条模板由usageType用途类型与content内容非空字符串构成。校验失败时getValidatedConfig会抛出ConnectorError(ConnectorErrorCodes.InvalidConfig)Logto 控制台会以此提示配置不合法见 index.ts。3.3 模板用途类型usageType与默认模板usageType取自 Logto 的TemplateType枚举见 passwordless.ts当前支持 9 种类型分别对应不同的验证码业务场景usageType业务场景SignIn用户登录时发送验证码Register用户注册时发送验证码ForgotPassword用户重置密码时发送验证码OrganizationInvitation发送组织邀请Generic通用场景亦作为未匹配类型的兜底模板UserPermissionValidation敏感操作前的用户权限验证BindNewIdentifier为既有账号绑定新标识MfaVerification发送 MFA 验证码BindMfa绑定 MFA 验证连接器为上述全部类型预置了默认模板内容您的验证码是 {{code}}。如非本人操作请忽略本短信因此即使不逐条自定义也能快速跑通验证码流程。3.4 模板匹配与占位符替换的底层机制模板的匹配与内容渲染复用了logto/connector-kit的两个共享函数理解它们有助于正确编写模板按类型取模板getConfigTemplateByType(type, config)会先在templates中查找与当前发送类型完全一致的条目若找不到则回退到Generic类型模板见 index.ts。这意味着你至少要配置一条Generic模板才能兜底所有未单独定制的场景。占位符渲染replaceSendMessageHandlebars(template, payload)使用正则/{{\s*([\w.])\s*}}/g扫描模板将{{code}}等占位符替换为 payload 中的对应值支持点号路径如{{application.name}}并且当占位符的根变量在 payload 中不存在时会原样保留占位符文本而不是替换为空见 index.ts。// 示例模板渲染结果 replaceSendMessageHandlebars(您的验证码是 {{code}}。如非本人操作请忽略本短信, { code: 1234 }); // 您的验证码是 1234。如非本人操作请忽略本短信若当前发送类型在配置的模板中不存在且无Generic兜底sendMessage会抛出TemplateNotFound错误测试用例should throw TemplateNotFound when template is not configured验证了该行为见 index.test.ts。发送流程一次验证码请求的完整生命周期当 Logto 核心需要发送验证码时会调用连接器的sendMessage函数。完整链路如下见 index.ts解析入参取出接收号码to、发送类型type与模板数据payload读取配置通过getConfig读取连接器配置支持调用方直接传入inputConfig覆盖并执行 zod 校验取模板并渲染按类型取模板用 payload 渲染出最终短信内容messageContent构造 GET 请求向短信宝接口https://api.smsbao.com/sms发起 HTTP GET携带以下查询参数查询参数来源说明u配置username短信宝用户名p配置passwordOrApiKeyAPI Key 或 MD5 密码g配置goodsId产品 ID仅当配置了goodsId时才携带见 index.tsm入参to接收手机号c渲染后的模板内容短信正文处理响应请求使用got库发送不启用重试retry.limit: 0并设置 5 秒请求超时defaultTimeout 5000见 constant.ts。测试用例should send message successfully与should omit product ID when goodsId is not configured分别验证了完整请求参数与goodsId省略逻辑见 index.test.ts测试中使用nock拦截真实网络请求通过nock.disableNetConnect()保证测试不发真实短信。错误码映射如何判断发送是否成功短信宝以响应文本返回结果返回0表示发送成功其余返回码一律被视为发送错误。连接器内置了一张错误码到可读信息的映射表见 index.ts返回码含义连接器映射-1短信宝请求参数不完整-2短信宝服务器环境不支持该请求30短信宝密码错误40短信宝账号不存在41短信宝账户余额不足42短信宝账号已过期43短信宝 IP 地址被限制50短信内容包含敏感词51手机号无效其他统一格式化为SMSBao SMS send failed: {code}当响应非0时连接器抛出ConnectorError(ConnectorErrorCodes.General, getErrorMessage(body))将错误码翻译为上述可读信息。测试should throw general error for SMSBao error response用返回码41验证了「余额不足」的报错路径见 index.test.ts。此外针对网络层异常连接器做了分级处理见 index.tsHTTP 错误如 500抛出General错误携带服务器响应体原文请求错误网络不通等抛出统一的SMSBao request failed提示避免向用户暴露底层网络细节其他未知异常透传错误消息。对应测试覆盖了 500 响应、网络错误与未知错误的全部路径见 index.test.ts。这份分级处理意味着遇到发送失败时可以先根据日志中的错误码快速定位是凭证问题30/40、余额问题41、内容问题50还是号码问题51再针对性处理。注意事项与最佳实践结合文档「注意事项」与源码实现给出如下实操建议仅支持国内短信余额查询、上行短信推送、国际短信和语音验证码 API 不在连接器范围内相关需求需另寻方案。以0为准判断成功只有响应体为0才算发送成功配置完建议先发送一条真实测试短信验证全链路。凭证不二次哈希填入的是 API Key 或已完成 MD5 的密码原值连接器原样传递请勿在 Logto 中再对凭证做哈希。模板内容须与短信宝审核结果一致Logto 中模板正文应和短信宝审核通过的模板保持一致否则可能因内容不一致导致审核或发送问题占位符统一使用{{code}}等 Logto 变量。务必配置Generic兜底模板由于模板匹配存在「找不到指定类型则回退Generic」的机制保留一条Generic模板可以避免新增业务场景时出现TemplateNotFound。生产前测试建议在正式使用前通过 Logto 的测试发送或真实注册/登录流程验证连接器配置包括模板渲染、请求参数与响应处理可用测试代码 index.test.ts 与配置样例 mock.ts 作为参考——mock.ts中给出了一组包含用户名、API Key、产品 ID 与四类模板的完整配置示例。参考与延伸阅读连接器实现主文件index.ts端点、超时与元数据定义constant.ts配置 zod 校验与类型types.ts单测用例成功/失败/兜底全路径index.test.ts完整配置样例mock.ts连接器包声明与构建方式package.json模板占位符替换与按类型取模板的共享实现connector-kit 核心工具短信/邮件模板类型枚举TemplateTypepasswordless.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 短信宝短信连接器接入指南：短信验证码登录、注册与模板配置实战
Logto 短信宝短信连接器接入指南短信验证码登录、注册与模板配置实战【免费下载链接】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 开源身份认证基础设施中的官方短信连接器——短信宝SMSBao短信服务展开完整讲解从短信宝平台侧的账号与凭证准备、模板审核到 Logto 管理控制台内的连接器配置、模板映射再到底层发送流程与错误码处理的全部环节。读完本文你将掌握如何在 Logto 中启用短信验证码登录、注册、重置密码等验证流程并理解该连接器在 index.ts 中真实请求构造与错误处理的实现原理。连接器是什么Logto 与短信宝的对接桥短信宝SMSBao是国内一家短信服务提供商。Logto 的短信宝短信连接器connector-smsbao-sms是该项目的官方连接器它的职责是将 Logto 的「发送验证码」事件翻译成对短信宝国内短信 API 的调用让终端用户通过手机短信验证码完成登录SignIn、注册Register、重置密码ForgotPassword以及 MFA 验证、绑定新标识等各类验证流程。从源码结构看该连接器属于标准的 Logto SMS 类型连接器导出createSmsbaoSmsConnector声明type: ConnectorType.Sms并通过sendMessage函数与 Logto 核心交互见 index.ts。整个包体积精简依赖logto/connector-kit、got与zod见 package.json。需要特别说明的是该连接器仅支持短信宝的国内短信发送余额查询、上行短信推送、国际短信和语音验证码等 API 均不在其功能范围内。第一步在短信宝平台完成配置在使用 Logto 之前需要先到短信宝完成账号与模板准备。此步骤全部在短信宝侧完成Logto 仅消费其凭证。1.1 创建短信宝账号访问短信宝官网注册账号并完成短信服务所需的账号配置包括必要的实名认证与签名/模板申请流程。1.2 获取连接凭证在短信宝后台准备以下三项配置信息配置项是否必填说明用户名username必填短信宝账号的用户名API Key 或 MD5 密码passwordOrApiKey必填推荐使用短信宝 API Key也可以使用短信宝登录密码的 MD5 值产品 IDgoodsId可选仅在使用短信宝专用通道产品时填写一个值得注意的实现细节是连接器会原样发送 API Key 或 MD5 密码不会在 Logto 中再次哈希。也就是说如果填入 MD5 密码请确保传入的就是已完成 MD5 运算后的值如果填入 API Key同样按原值提交。这一点在 index.ts 中可见u: username, p: passwordOrApiKey直接作为查询参数发出不做任何二次处理。1.3 配置并审核短信模板在短信宝后台创建短信模板并等待审核通过后再启用连接器。Logto 中配置的模板内容应与短信宝审核通过的内容保持一致并使用{{code}}这类 Logto 占位符标记验证码插入位置。第二步在 Logto 管理控制台中启用连接器在短信宝侧准备就绪后按以下步骤在 Logto 中完成配置进入 Logto 管理控制台打开「连接器」页面找到并点击「短信宝短信服务」对应元数据中的SMSBao SMS Service见 constant.ts在配置表单中依次填入用户名短信宝用户名API Key 或 MD5 密码短信宝 API Key 或已做 MD5 的密码产品 ID可选的专用通道产品 ID短信模板按 Logto 用途类型配置对应模板内容。保存后即可在登录、注册等体验配置中将该短信通道指定为验证码发送渠道。配置字段与模板结构深度解析控制台中的表单字段并非写死在页面里而是由连接器通过metadata.formItems声明的见 constant.ts。理解这套声明有助于把握每个字段的校验规则与默认值。3.1 连接器配置表单字段表单字段类型必填是否机密默认值/占位提示username文本是否usernamepasswordOrApiKey文本是是机密字段api-key-or-md5-passwordgoodsId文本否否product-idtemplatesJSON是否内置 9 类默认模板内容均为「您的验证码是 {{code}}。如非本人操作请忽略本短信」其中passwordOrApiKey被标记为机密字段isConfidential: true在管理控制台中会被加密存储避免凭证明文暴露。3.2 配置的运行时校验规则提交后的配置会经过smsbaoSmsConfigGuardzod schema校验只有通过校验的连接器才能正常工作见 types.tsconst smsbaoSmsConfigGuard z.object({ username: z.string().min(1), passwordOrApiKey: z.string().min(1), goodsId: z.string().min(1).optional(), templates: z.array(templateGuard).min(1), });即username、passwordOrApiKey均不可为空字符串goodsId可选一旦填写至少 1 个字符templates至少需要配置 1 条模板。每条模板由usageType用途类型与content内容非空字符串构成。校验失败时getValidatedConfig会抛出ConnectorError(ConnectorErrorCodes.InvalidConfig)Logto 控制台会以此提示配置不合法见 index.ts。3.3 模板用途类型usageType与默认模板usageType取自 Logto 的TemplateType枚举见 passwordless.ts当前支持 9 种类型分别对应不同的验证码业务场景usageType业务场景SignIn用户登录时发送验证码Register用户注册时发送验证码ForgotPassword用户重置密码时发送验证码OrganizationInvitation发送组织邀请Generic通用场景亦作为未匹配类型的兜底模板UserPermissionValidation敏感操作前的用户权限验证BindNewIdentifier为既有账号绑定新标识MfaVerification发送 MFA 验证码BindMfa绑定 MFA 验证连接器为上述全部类型预置了默认模板内容您的验证码是 {{code}}。如非本人操作请忽略本短信因此即使不逐条自定义也能快速跑通验证码流程。3.4 模板匹配与占位符替换的底层机制模板的匹配与内容渲染复用了logto/connector-kit的两个共享函数理解它们有助于正确编写模板按类型取模板getConfigTemplateByType(type, config)会先在templates中查找与当前发送类型完全一致的条目若找不到则回退到Generic类型模板见 index.ts。这意味着你至少要配置一条Generic模板才能兜底所有未单独定制的场景。占位符渲染replaceSendMessageHandlebars(template, payload)使用正则/{{\s*([\w.])\s*}}/g扫描模板将{{code}}等占位符替换为 payload 中的对应值支持点号路径如{{application.name}}并且当占位符的根变量在 payload 中不存在时会原样保留占位符文本而不是替换为空见 index.ts。// 示例模板渲染结果 replaceSendMessageHandlebars(您的验证码是 {{code}}。如非本人操作请忽略本短信, { code: 1234 }); // 您的验证码是 1234。如非本人操作请忽略本短信若当前发送类型在配置的模板中不存在且无Generic兜底sendMessage会抛出TemplateNotFound错误测试用例should throw TemplateNotFound when template is not configured验证了该行为见 index.test.ts。发送流程一次验证码请求的完整生命周期当 Logto 核心需要发送验证码时会调用连接器的sendMessage函数。完整链路如下见 index.ts解析入参取出接收号码to、发送类型type与模板数据payload读取配置通过getConfig读取连接器配置支持调用方直接传入inputConfig覆盖并执行 zod 校验取模板并渲染按类型取模板用 payload 渲染出最终短信内容messageContent构造 GET 请求向短信宝接口https://api.smsbao.com/sms发起 HTTP GET携带以下查询参数查询参数来源说明u配置username短信宝用户名p配置passwordOrApiKeyAPI Key 或 MD5 密码g配置goodsId产品 ID仅当配置了goodsId时才携带见 index.tsm入参to接收手机号c渲染后的模板内容短信正文处理响应请求使用got库发送不启用重试retry.limit: 0并设置 5 秒请求超时defaultTimeout 5000见 constant.ts。测试用例should send message successfully与should omit product ID when goodsId is not configured分别验证了完整请求参数与goodsId省略逻辑见 index.test.ts测试中使用nock拦截真实网络请求通过nock.disableNetConnect()保证测试不发真实短信。错误码映射如何判断发送是否成功短信宝以响应文本返回结果返回0表示发送成功其余返回码一律被视为发送错误。连接器内置了一张错误码到可读信息的映射表见 index.ts返回码含义连接器映射-1短信宝请求参数不完整-2短信宝服务器环境不支持该请求30短信宝密码错误40短信宝账号不存在41短信宝账户余额不足42短信宝账号已过期43短信宝 IP 地址被限制50短信内容包含敏感词51手机号无效其他统一格式化为SMSBao SMS send failed: {code}当响应非0时连接器抛出ConnectorError(ConnectorErrorCodes.General, getErrorMessage(body))将错误码翻译为上述可读信息。测试should throw general error for SMSBao error response用返回码41验证了「余额不足」的报错路径见 index.test.ts。此外针对网络层异常连接器做了分级处理见 index.tsHTTP 错误如 500抛出General错误携带服务器响应体原文请求错误网络不通等抛出统一的SMSBao request failed提示避免向用户暴露底层网络细节其他未知异常透传错误消息。对应测试覆盖了 500 响应、网络错误与未知错误的全部路径见 index.test.ts。这份分级处理意味着遇到发送失败时可以先根据日志中的错误码快速定位是凭证问题30/40、余额问题41、内容问题50还是号码问题51再针对性处理。注意事项与最佳实践结合文档「注意事项」与源码实现给出如下实操建议仅支持国内短信余额查询、上行短信推送、国际短信和语音验证码 API 不在连接器范围内相关需求需另寻方案。以0为准判断成功只有响应体为0才算发送成功配置完建议先发送一条真实测试短信验证全链路。凭证不二次哈希填入的是 API Key 或已完成 MD5 的密码原值连接器原样传递请勿在 Logto 中再对凭证做哈希。模板内容须与短信宝审核结果一致Logto 中模板正文应和短信宝审核通过的模板保持一致否则可能因内容不一致导致审核或发送问题占位符统一使用{{code}}等 Logto 变量。务必配置Generic兜底模板由于模板匹配存在「找不到指定类型则回退Generic」的机制保留一条Generic模板可以避免新增业务场景时出现TemplateNotFound。生产前测试建议在正式使用前通过 Logto 的测试发送或真实注册/登录流程验证连接器配置包括模板渲染、请求参数与响应处理可用测试代码 index.test.ts 与配置样例 mock.ts 作为参考——mock.ts中给出了一组包含用户名、API Key、产品 ID 与四类模板的完整配置示例。参考与延伸阅读连接器实现主文件index.ts端点、超时与元数据定义constant.ts配置 zod 校验与类型types.ts单测用例成功/失败/兜底全路径index.test.ts完整配置样例mock.ts连接器包声明与构建方式package.json模板占位符替换与按类型取模板的共享实现connector-kit 核心工具短信/邮件模板类型枚举TemplateTypepasswordless.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），仅供参考