Lightdash OneLogin SSO 实现解析从同步策略构建到按组织动态注册的完整链路【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdashLightdash 支持两条并行的 OneLogin 单点登录路径基于环境变量、面向整个实例的实例级配置以及存储于数据库、面向共享多组织部署的按组织配置。本文基于 docs/onelogin-sso.md 展开并结合 oneLoginStrategy.ts、apiV1Router.ts 等源码讲清 OneLogin SSO 的策略构建机制、动态注册与缓存原理、配置字段、发现流程和完整的文件地图读完后你可以理解 Lightdash 如何在一个实例上为不同组织分别接入各自的 OneLogin 租户。一、两条并行的 OneLogin SSO 路径Lightdash 中的 OneLogin SSO 遵循与 Azure AD SSO 相同的模型两者共享发现discovery、跨组织过滤cross-org filter和灰度发布rollout机制实例级env-based通过环境变量配置一个 OneLogin 应用对实例上的所有用户生效是最早的实现按组织per-orgDB-stored在共享多组织实例上每个组织通过Settings → Single Sign-On管理面板配置自己的 OneLogin 应用。两条路径并存且当按组织配置命中用户邮箱域名时按组织配置优先于实例级配置会抑制后者。OneLogin 文档只覆盖 OneLogin 特有的部分发现流程、跨组织过滤、灰度开关sso-organization-settingsfeature flag等共享机制可参考 Azure AD 文档。二、策略机制从 issuer 模板化端点同步构建策略OneLogin 与通用 OIDC见 OIDC SSO 文档的关键区别在于它使用passport-openidconnect且各端点直接从 issuer 模板化生成{issuer}/oidc/2/auth、/token、/me因此构建策略是同步的——无需访问 issuer 的 discovery 文档。这与 Azure AD端点由 tenant ID 模板化一致而不同于通用 OIDC 的Issuer.discover()异步发现。核心构建函数createOneLoginStrategyForConfig位于 oneLoginStrategy.tsexport const createOneLoginStrategyForConfig ( config: OneLoginSsoConfig, organizationUuid?: string, ): OpenIDConnectStrategy new OpenIDConnectStrategy( { clientID: config.oauth2ClientId, clientSecret: config.oauth2ClientSecret, issuer: new URL(/oidc/2, config.oauth2Issuer).href, callbackURL: new URL( /api/v1${lightdashConfig.auth.oneLogin.callbackPath}, lightdashConfig.siteUrl, ).href, authorizationURL: new URL(/oidc/2/auth, config.oauth2Issuer).href, tokenURL: new URL(/oidc/2/token, config.oauth2Issuer).href, userInfoURL: new URL(/oidc/2/me, config.oauth2Issuer).href, passReqToCallback: true, }, genericOidcHandler( OpenIdIdentityIssuerType.ONELOGIN, undefined, organizationUuid ? { organizationUuid, provider: OrganizationSsoProvider.ONELOGIN, } : undefined, ), );从源码可以看到几个要点三个端点均由 issuer 推导authorizationURL、tokenURL、userInfoURL分别为{issuer}/oidc/2/auth、{issuer}/oidc/2/token、{issuer}/oidc/2/meissuer选项则取{issuer}/oidc/2。这正是无需 discovery、同步构建的原因回调地址由siteUrl与配置的callbackPath拼接即默认/api/v1/oauth/redirect/oneLogin组织上下文透传当传入organizationUuid按组织路径时通过genericOidcHandler携带{ organizationUuid, provider: OrganizationSsoProvider.ONELOGIN }用于回调后把用户匹配到正确的组织认证回调逻辑复用oidcStrategy.ts中的genericOidcHandlerOneLogin 与通用 OIDC 共用同一套处理管线仅 issuer 类型不同。实例级env-based路径环境变量在 parseConfig.ts 中解析环境变量对应配置AUTH_ONE_LOGIN_OAUTH_ISSUEROneLogin OIDC issuer URLAUTH_ONE_LOGIN_OAUTH_CLIENT_IDOneLogin 应用 Client IDAUTH_ONE_LOGIN_OAUTH_CLIENT_SECRETOneLogin 应用 Client SecretloginPath/callbackPath固定为/login/oneLogin与/oauth/redirect/oneLogin可用性由isOneLoginPassportStrategyAvailableToUse判定oneLoginStrategy.ts三个字段齐备才可用。可用时env-based 的oneLoginPassportStrategy与按组织路径共用同一个构建器oneLoginStrategy.tsexport const oneLoginPassportStrategy isOneLoginPassportStrategyAvailableToUse ? createOneLoginStrategyForConfig({ oauth2ClientId: lightdashConfig.auth.oneLogin.oauth2ClientId!, oauth2ClientSecret: lightdashConfig.auth.oneLogin.oauth2ClientSecret!, oauth2Issuer: lightdashConfig.auth.oneLogin.oauth2Issuer!, }) : undefined;该策略在App.ts启动时以名称oneLogin注册作为按组织配置不可用时的回退fallback。三、按组织路径动态策略缓存、解析与回调重注册按组织策略的动态注册逻辑集中在 apiV1Router.ts完全镜像 Azure AD 的缓存模式。策略缓存与注册每个组织的策略以oneLogin:orgUuid命名注册到 passport并维护一个带10 分钟 TTL的缓存apiV1Router.tsconst oneLoginStrategyCache new Map string, { timer: ReturnTypetypeof setTimeout } (); const registerOneLoginStrategyForOrg ( organizationUuid: string, config: import(lightdash/common).OneLoginSsoConfig, ): string { const strategyName oneLogin:${organizationUuid}; const existing oneLoginStrategyCache.get(strategyName); passport.use( strategyName, createOneLoginStrategyForConfig(config, organizationUuid), ); if (existing) { clearTimeout(existing.timer); } const timer setTimeout(() { oneLoginStrategyCache.delete(strategyName); passport.unuse(strategyName); }, AZURE_AD_STRATEGY_TTL_MS); oneLoginStrategyCache.set(strategyName, { timer }); return strategyName; };由于 OneLogin 端点是同步模板化的registerOneLoginStrategyForOrg是同步函数——对比之下通用 OIDC 因 discovery 网络请求其注册函数是async的。每次重新注册会清理上一个 timer每次请求都重新注册因此配置变更例如轮换 secret会及时生效。按邮箱 login-hint 解析策略名resolveOneLoginStrategyNameapiV1Router.ts的解析顺序从请求中取login_hint用户邮箱调用OrganizationSsoService.findEnabledMethodForEmail(email, OrganizationSsoProvider.ONELOGIN)查找命中的按组织配置命中则注册并返回oneLogin:orgUuid未命中时若 env-based 策略可用回退返回oneLogin两者都不可用则返回undefined路由侧返回 404OneLogin SSO is not configured。登录与回调路由登录路由GET /api/v1/login/oneLoginapiV1Router.ts解析策略名后把名字存入req.session.oauth.oneLoginStrategyName再以scope: [openid, profile, email]发起passport.authenticate(strategyName, …)回调路由GET /api/v1/oauth/redirect/oneLoginapiV1Router.ts优先从 session 读回策略名session 缺失时重新解析若策略名形如oneLogin:orgUuid且缓存已被驱逐例如登录和回调之间发生了服务重启则用organizationUuid从数据库重新取出配置并调用registerOneLoginStrategyForOrg重新注册随后执行passport.authenticate失败/成功分别重定向到getOidcRedirectURL(false/true)(req)指定的页面。这条session 存策略名 回调按需重注册的链路是 per-org SSO 在重启、缓存驱逐等情况下仍能正确完成 OAuth 会话的关键设计。四、配置字段与加密存储按组织配置以加密形式存储在organization_sso_configurations表中provider oneLogin。OneLogin 特有的字段字段用途oauth2IssuerOneLogin OIDC issuer URLauth/token/userinfo 端点均由它推导oauth2ClientId/oauth2ClientSecretOneLogin 应用凭据。secret 加密存储、永不回传API 响应中以hasClientSecret布尔值代替表结构含enabled、override_email_domains、email_domains、allow_password等共享列由 migration 创建并经后续 migration 扩展config列为加密 JSONAES-256-GCM密钥派生自LIGHTDASH_SECRET。共享标志列与 Azure AD 行为一致列行为enabled该 SSO 方式的主开关。关闭后对任何人不可见override_email_domains为 true 时由本行的email_domains白名单主导发现为 false 时使用组织既有的organization_allowed_email_domains列表email_domains严格白名单仅在override_email_domains true时生效列表为空且 override 开启 该方式对发现不可见allow_password为 true 时命中该方式的用户仍可邮箱/密码登录为 false 时隐藏密码输入只呈现 OneLogin 按钮完整的发现流程getLoginOptions→findEnabledMethodsForEmailDomain→ 匹配行替换实例级 provider → 密码框宽松可见规则与跨组织过滤逻辑见 Azure AD 文档。五、发现、登录选项与管理端点getLoginOptions是 provider 无关的oneLogin以 1:1 映射到OpenIdIdentityIssuerType.ONELOGIN因此发现、force-redirect新用户唯一命中时自动跳转和密码抑制行为与 Azure 完全一致无需单独实现管理 API 端点定义于 OrganizationSsoController.tsGET /api/v1/org/sso/oneLoginGetOneLoginSsoConfig— 返回当前组织的 OneLogin 配置摘要脱敏PUT /api/v1/org/sso/oneLoginUpsertOneLoginSsoConfig— 创建/更新配置DELETE /api/v1/org/sso/oneLoginDeleteOneLoginSsoConfig— 删除配置未配置时抛NotFoundError。服务层实现位于 OrganizationSsoService.ts 的getOneLoginConfig/upsertOneLoginConfig/deleteOneLoginConfigupsert 路径会对oauth2Issuer做 URL 校验OneLogin issuer URL。管理面板受manage OrganizationCASL 能力与sso-organization-settingsfeature flag 双重门禁发布方式共享云端按组织插feature_flag_overrides行或自托管设置ENABLED_FEATURE_FLAGSsso-organization-settings与 Azure AD 相同。六、前端组件管理面板OneLoginSsoPanel.tsx 复用ONELOGIN_LOGO供组织管理员填写 issuer / client ID / client secret 并切换共享标志列数据 hooksuseOrganizationSso.ts 中的useOneLoginSsoConfig系列 hooks 负责配置的读取与保存登录页按钮ThirdPartySignInButton 在ONELOGIN分支支持forceShow配合 force-redirect 场景直接呈现 OneLogin 登录按钮。七、OneLogin 相关文件地图路径用途packages/common/src/types/organizationSso.tsONELOGINprovider 枚举、OneLoginSsoConfig及 summary/upsert/response 类型定义packages/backend/src/models/OrganizationSsoModel.tsprovider 映射表中ONELOGIN → OneLoginSsoConfigpackages/backend/src/services/OrganizationSsoService/OrganizationSsoService.tsget/upsert/deleteOneLoginConfig服务方法packages/backend/src/ee/controllers/OrganizationSsoController.ts/api/v1/org/sso/oneLogin三个管理端点packages/backend/src/controllers/authentication/strategies/oneLoginStrategy.tscreateOneLoginStrategyForConfig构建器与可用性判定packages/backend/src/routers/apiV1Router.tsoneLogin:orgUuid策略缓存与解析、登录/回调路由改造packages/frontend/src/components/UserSettings/OrganizationSso/OneLoginSsoPanel.tsx组织管理员面板 UIpackages/frontend/src/hooks/organization/useOrganizationSso.tsuseOneLoginSsoConfighooks八、小结Lightdash 的 OneLogin SSO 是模板化端点 同步策略构建 按组织动态注册三者的组合端点由 issuer 推导使其免 discovery、构建同步oneLogin:orgUuid命名空间加 10 分钟 TTL 缓存使共享实例可并行承载多组织session 中存储策略名、回调时按 DB 重注册则保证了服务重启后的会话连续性。整体架构与 Azure AD 完全同构因此阅读 azure-ad-sso.md 是理解 OneLogin 路径的前提而 OneLogin 特有的差异集中在 oneLoginStrategy.ts 的端点模板与 apiV1Router.ts 的缓存解析逻辑这两处。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Lightdash OneLogin SSO 实现解析从同步策略构建到按组织动态注册的完整链路【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdashLightdash 支持两条并行的 OneLogin 单点登录路径基于环境变量、面向整个实例的实例级配置以及存储于数据库、面向共享多组织部署的按组织配置。本文基于 docs/onelogin-sso.md 展开并结合 oneLoginStrategy.ts、apiV1Router.ts 等源码讲清 OneLogin SSO 的策略构建机制、动态注册与缓存原理、配置字段、发现流程和完整的文件地图读完后你可以理解 Lightdash 如何在一个实例上为不同组织分别接入各自的 OneLogin 租户。一、两条并行的 OneLogin SSO 路径Lightdash 中的 OneLogin SSO 遵循与 Azure AD SSO 相同的模型两者共享发现discovery、跨组织过滤cross-org filter和灰度发布rollout机制实例级env-based通过环境变量配置一个 OneLogin 应用对实例上的所有用户生效是最早的实现按组织per-orgDB-stored在共享多组织实例上每个组织通过Settings → Single Sign-On管理面板配置自己的 OneLogin 应用。两条路径并存且当按组织配置命中用户邮箱域名时按组织配置优先于实例级配置会抑制后者。OneLogin 文档只覆盖 OneLogin 特有的部分发现流程、跨组织过滤、灰度开关sso-organization-settingsfeature flag等共享机制可参考 Azure AD 文档。二、策略机制从 issuer 模板化端点同步构建策略OneLogin 与通用 OIDC见 OIDC SSO 文档的关键区别在于它使用passport-openidconnect且各端点直接从 issuer 模板化生成{issuer}/oidc/2/auth、/token、/me因此构建策略是同步的——无需访问 issuer 的 discovery 文档。这与 Azure AD端点由 tenant ID 模板化一致而不同于通用 OIDC 的Issuer.discover()异步发现。核心构建函数createOneLoginStrategyForConfig位于 oneLoginStrategy.tsexport const createOneLoginStrategyForConfig ( config: OneLoginSsoConfig, organizationUuid?: string, ): OpenIDConnectStrategy new OpenIDConnectStrategy( { clientID: config.oauth2ClientId, clientSecret: config.oauth2ClientSecret, issuer: new URL(/oidc/2, config.oauth2Issuer).href, callbackURL: new URL( /api/v1${lightdashConfig.auth.oneLogin.callbackPath}, lightdashConfig.siteUrl, ).href, authorizationURL: new URL(/oidc/2/auth, config.oauth2Issuer).href, tokenURL: new URL(/oidc/2/token, config.oauth2Issuer).href, userInfoURL: new URL(/oidc/2/me, config.oauth2Issuer).href, passReqToCallback: true, }, genericOidcHandler( OpenIdIdentityIssuerType.ONELOGIN, undefined, organizationUuid ? { organizationUuid, provider: OrganizationSsoProvider.ONELOGIN, } : undefined, ), );从源码可以看到几个要点三个端点均由 issuer 推导authorizationURL、tokenURL、userInfoURL分别为{issuer}/oidc/2/auth、{issuer}/oidc/2/token、{issuer}/oidc/2/meissuer选项则取{issuer}/oidc/2。这正是无需 discovery、同步构建的原因回调地址由siteUrl与配置的callbackPath拼接即默认/api/v1/oauth/redirect/oneLogin组织上下文透传当传入organizationUuid按组织路径时通过genericOidcHandler携带{ organizationUuid, provider: OrganizationSsoProvider.ONELOGIN }用于回调后把用户匹配到正确的组织认证回调逻辑复用oidcStrategy.ts中的genericOidcHandlerOneLogin 与通用 OIDC 共用同一套处理管线仅 issuer 类型不同。实例级env-based路径环境变量在 parseConfig.ts 中解析环境变量对应配置AUTH_ONE_LOGIN_OAUTH_ISSUEROneLogin OIDC issuer URLAUTH_ONE_LOGIN_OAUTH_CLIENT_IDOneLogin 应用 Client IDAUTH_ONE_LOGIN_OAUTH_CLIENT_SECRETOneLogin 应用 Client SecretloginPath/callbackPath固定为/login/oneLogin与/oauth/redirect/oneLogin可用性由isOneLoginPassportStrategyAvailableToUse判定oneLoginStrategy.ts三个字段齐备才可用。可用时env-based 的oneLoginPassportStrategy与按组织路径共用同一个构建器oneLoginStrategy.tsexport const oneLoginPassportStrategy isOneLoginPassportStrategyAvailableToUse ? createOneLoginStrategyForConfig({ oauth2ClientId: lightdashConfig.auth.oneLogin.oauth2ClientId!, oauth2ClientSecret: lightdashConfig.auth.oneLogin.oauth2ClientSecret!, oauth2Issuer: lightdashConfig.auth.oneLogin.oauth2Issuer!, }) : undefined;该策略在App.ts启动时以名称oneLogin注册作为按组织配置不可用时的回退fallback。三、按组织路径动态策略缓存、解析与回调重注册按组织策略的动态注册逻辑集中在 apiV1Router.ts完全镜像 Azure AD 的缓存模式。策略缓存与注册每个组织的策略以oneLogin:orgUuid命名注册到 passport并维护一个带10 分钟 TTL的缓存apiV1Router.tsconst oneLoginStrategyCache new Map string, { timer: ReturnTypetypeof setTimeout } (); const registerOneLoginStrategyForOrg ( organizationUuid: string, config: import(lightdash/common).OneLoginSsoConfig, ): string { const strategyName oneLogin:${organizationUuid}; const existing oneLoginStrategyCache.get(strategyName); passport.use( strategyName, createOneLoginStrategyForConfig(config, organizationUuid), ); if (existing) { clearTimeout(existing.timer); } const timer setTimeout(() { oneLoginStrategyCache.delete(strategyName); passport.unuse(strategyName); }, AZURE_AD_STRATEGY_TTL_MS); oneLoginStrategyCache.set(strategyName, { timer }); return strategyName; };由于 OneLogin 端点是同步模板化的registerOneLoginStrategyForOrg是同步函数——对比之下通用 OIDC 因 discovery 网络请求其注册函数是async的。每次重新注册会清理上一个 timer每次请求都重新注册因此配置变更例如轮换 secret会及时生效。按邮箱 login-hint 解析策略名resolveOneLoginStrategyNameapiV1Router.ts的解析顺序从请求中取login_hint用户邮箱调用OrganizationSsoService.findEnabledMethodForEmail(email, OrganizationSsoProvider.ONELOGIN)查找命中的按组织配置命中则注册并返回oneLogin:orgUuid未命中时若 env-based 策略可用回退返回oneLogin两者都不可用则返回undefined路由侧返回 404OneLogin SSO is not configured。登录与回调路由登录路由GET /api/v1/login/oneLoginapiV1Router.ts解析策略名后把名字存入req.session.oauth.oneLoginStrategyName再以scope: [openid, profile, email]发起passport.authenticate(strategyName, …)回调路由GET /api/v1/oauth/redirect/oneLoginapiV1Router.ts优先从 session 读回策略名session 缺失时重新解析若策略名形如oneLogin:orgUuid且缓存已被驱逐例如登录和回调之间发生了服务重启则用organizationUuid从数据库重新取出配置并调用registerOneLoginStrategyForOrg重新注册随后执行passport.authenticate失败/成功分别重定向到getOidcRedirectURL(false/true)(req)指定的页面。这条session 存策略名 回调按需重注册的链路是 per-org SSO 在重启、缓存驱逐等情况下仍能正确完成 OAuth 会话的关键设计。四、配置字段与加密存储按组织配置以加密形式存储在organization_sso_configurations表中provider oneLogin。OneLogin 特有的字段字段用途oauth2IssuerOneLogin OIDC issuer URLauth/token/userinfo 端点均由它推导oauth2ClientId/oauth2ClientSecretOneLogin 应用凭据。secret 加密存储、永不回传API 响应中以hasClientSecret布尔值代替表结构含enabled、override_email_domains、email_domains、allow_password等共享列由 migration 创建并经后续 migration 扩展config列为加密 JSONAES-256-GCM密钥派生自LIGHTDASH_SECRET。共享标志列与 Azure AD 行为一致列行为enabled该 SSO 方式的主开关。关闭后对任何人不可见override_email_domains为 true 时由本行的email_domains白名单主导发现为 false 时使用组织既有的organization_allowed_email_domains列表email_domains严格白名单仅在override_email_domains true时生效列表为空且 override 开启 该方式对发现不可见allow_password为 true 时命中该方式的用户仍可邮箱/密码登录为 false 时隐藏密码输入只呈现 OneLogin 按钮完整的发现流程getLoginOptions→findEnabledMethodsForEmailDomain→ 匹配行替换实例级 provider → 密码框宽松可见规则与跨组织过滤逻辑见 Azure AD 文档。五、发现、登录选项与管理端点getLoginOptions是 provider 无关的oneLogin以 1:1 映射到OpenIdIdentityIssuerType.ONELOGIN因此发现、force-redirect新用户唯一命中时自动跳转和密码抑制行为与 Azure 完全一致无需单独实现管理 API 端点定义于 OrganizationSsoController.tsGET /api/v1/org/sso/oneLoginGetOneLoginSsoConfig— 返回当前组织的 OneLogin 配置摘要脱敏PUT /api/v1/org/sso/oneLoginUpsertOneLoginSsoConfig— 创建/更新配置DELETE /api/v1/org/sso/oneLoginDeleteOneLoginSsoConfig— 删除配置未配置时抛NotFoundError。服务层实现位于 OrganizationSsoService.ts 的getOneLoginConfig/upsertOneLoginConfig/deleteOneLoginConfigupsert 路径会对oauth2Issuer做 URL 校验OneLogin issuer URL。管理面板受manage OrganizationCASL 能力与sso-organization-settingsfeature flag 双重门禁发布方式共享云端按组织插feature_flag_overrides行或自托管设置ENABLED_FEATURE_FLAGSsso-organization-settings与 Azure AD 相同。六、前端组件管理面板OneLoginSsoPanel.tsx 复用ONELOGIN_LOGO供组织管理员填写 issuer / client ID / client secret 并切换共享标志列数据 hooksuseOrganizationSso.ts 中的useOneLoginSsoConfig系列 hooks 负责配置的读取与保存登录页按钮ThirdPartySignInButton 在ONELOGIN分支支持forceShow配合 force-redirect 场景直接呈现 OneLogin 登录按钮。七、OneLogin 相关文件地图路径用途packages/common/src/types/organizationSso.tsONELOGINprovider 枚举、OneLoginSsoConfig及 summary/upsert/response 类型定义packages/backend/src/models/OrganizationSsoModel.tsprovider 映射表中ONELOGIN → OneLoginSsoConfigpackages/backend/src/services/OrganizationSsoService/OrganizationSsoService.tsget/upsert/deleteOneLoginConfig服务方法packages/backend/src/ee/controllers/OrganizationSsoController.ts/api/v1/org/sso/oneLogin三个管理端点packages/backend/src/controllers/authentication/strategies/oneLoginStrategy.tscreateOneLoginStrategyForConfig构建器与可用性判定packages/backend/src/routers/apiV1Router.tsoneLogin:orgUuid策略缓存与解析、登录/回调路由改造packages/frontend/src/components/UserSettings/OrganizationSso/OneLoginSsoPanel.tsx组织管理员面板 UIpackages/frontend/src/hooks/organization/useOrganizationSso.tsuseOneLoginSsoConfighooks八、小结Lightdash 的 OneLogin SSO 是模板化端点 同步策略构建 按组织动态注册三者的组合端点由 issuer 推导使其免 discovery、构建同步oneLogin:orgUuid命名空间加 10 分钟 TTL 缓存使共享实例可并行承载多组织session 中存储策略名、回调时按 DB 重注册则保证了服务重启后的会话连续性。整体架构与 Azure AD 完全同构因此阅读 azure-ad-sso.md 是理解 OneLogin 路径的前提而 OneLogin 特有的差异集中在 oneLoginStrategy.ts 的端点模板与 apiV1Router.ts 的缓存解析逻辑这两处。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
函数详解：字符串拼接的用法、NULL处理与性能优化)
