Logto Azure AD 连接器版本演进解析prompt、scopes 与 disableEmailSync 的设计与实现【免费下载链接】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本文以packages/connectors/connector-azuread/CHANGELOG.md为主线梳理 Logto 官方 Microsoft Azure AD 社交连接器logto/connector-azuread从 1.0.1 到 1.7.0 的完整版本演进。结合该包的源码src/index.ts、src/types.ts、src/constant.ts与测试用例逐项解释每个版本变更背后的实现方式——尤其是最新的disableEmailSync开关如何切断 Microsoft Graphmail属性与用户资料的绑定帮助你理解 Logto 社交连接器的配置语义、版本升级路径与源码级验证手段。连接器定位与代码结构Logto 的 Azure AD 连接器是一个Social类型连接器元数据 ID 为azuread-universaltarget 为azuread它基于azure/msal-node的ConfidentialClientApplication实现 OAuth 2.0 授权码流程并在拿到 access token 后调用 Microsoft Graph 的/v1.0/me接口获取用户资料。从 CHANGELOG 可以看出该包的核心依赖始终是logto/connector-kit连接器的公共类型与工具库版本演进中有大量条目是跟随 connector-kit 升级而触发的依赖更新。包的目录结构与关键文件如下文件职责src/index.ts连接器主体getAuthorizationUri、getAccessToken、getUserInfo三大方法src/types.ts基于 zod 的配置校验azureADConfigGuard与 Graph 响应校验src/constant.ts默认元数据、控制台表单项formItems、默认 scope、Graph 端点与超时src/index.test.ts基于 vitest nock 的单元测试覆盖 Graph 响应校验与disableEmailSync行为package.json版本1.7.0、依赖声明、tsup构建脚本、Node 引擎要求README.md面向使用者的集成指南Azure Portal 配置 Logto 侧配置说明版本演进总览以下是 CHANGELOG.md 记录的完整版本历史可整体概括为三条演进线认证行为可配置化prompt → scopes → 自定义 scope、数据可信度治理rawData 存储 → disableEmailSync、工程基线升级Node LTS 与构建工具版本类型变更摘要1.7.0Minor新增disableEmailSync开关使 Graphmail属性同步到用户资料的行为可配置commitc81931eab41.6.5Patch依赖更新logto/connector-kit升级至 5.1.01.6.4Patch依赖更新connector-kit 5.0.11.6.3Patch依赖更新connector-kit 5.0.01.6.2Patch依赖更新connector-kit 4.7.01.6.1Patch依赖更新connector-kit 4.6.01.6.0MinorgetAuthorizationUri方法支持自定义scope参数commit34964af461.5.0MinorNode 版本要求提升到^22.14.01.4.2Patch新增scopes配置字段1.4.1Patch依赖安全升级1.4.0Minor构建工具切换到tsup以 Minor 版本提醒使用者注意1.3.0Minor支持prompt配置1.2.0Minor返回并存储社交连接器原始数据rawData同时重写 Microsoft 集成指南专门澄清不同 access type 对应的 Tenant ID1.1.0Minor引擎要求切换为 Node 20 LTS因 Logto 以 Docker 镜像交付对用户不具破坏性1.0.1Patch依赖更新connector-kit 2.0.0可以看到从 1.6.1 到 1.6.5 连续多个 Patch 版本都没有本包自身的功能变更仅是跟随 connector-kit 的依赖升级发布。这种版本跟随模式说明连接器包与工具包之间保持着严格的版本联动。认证行为可配置化从 prompt 到 scope 的三步演进1.3.0支持prompt配置prompt是 OIDC 授权请求参数用于控制用户交互行为。连接器的prompts配置项在 src/constant.ts 中定义为一个MultiSelect表单项其可选值来自 connector-kit 导出的OidcPrompt枚举// packages/toolkit/connector-kit/src/types/social.ts export enum OidcPrompt { None none, Login login, Consent consent, SelectAccount select_account, }在 src/index.ts 中多个 prompt 会以空格拼接后写入授权 URL...conditional(prompts prompts.length 0 { prompt: prompts.join( ) }),配置校验则复用 connector-kit 的oidcPromptsGuard见 src/types.ts。各取值的语义在 README.md 中有明确说明promptlogin强制用户重新输入凭据、promptnone要求静默完成 SSO否则返回interaction_required错误、promptconsent触发授权同意对话框、promptselect_account打断 SSO 让用户选择账号。1.4.2新增scopes配置字段1.4.2 在配置模型中加入了可选的scopes字段src/types.tsscopes: z.string().optional()。它接受空格分隔的 scope 列表控制台表单中对应一个Text输入框placeholder 为scope1 scope2src/constant.ts。不填时使用默认值User.Read定义在 src/constant.ts。1.6.0getAuthorizationUri支持运行时自定义 scope1.6.0 的变更把scope从静态配置扩展为动态参数getAuthorizationUri方法的入参新增可选的scope字段。从 src/index.ts 的实现可以看到两条路径的取舍逻辑——若调用方显式传入scope则直接按其拆分结果使用否则回退为默认 scope 配置项 scope 去重合并const defaultAuthCodeUrlParameters: AuthorizationUrlRequest { scopes: scope ? scope.split( ) : deduplicate([...defaultScopes, ...(scopes?.split( ) ?? [])]), state, redirectUri, ...conditional(prompts prompts.length 0 { prompt: prompts.join( ) }), };这一签名来源于 connector-kit 的公共类型定义GetAuthorizationUripayload 中包含scope?: string见 packages/toolkit/connector-kit/src/types/social.ts意味着该能力由工具包统一约定、各社交连接器共同实现为不同登录场景请求不同授权范围提供了更灵活的空间。授权 URL 的构造过程本身依赖 MSAL连接器以cloudInstance tenantId拼接出 authoritysrc/index.ts因此 README 中Tenant ID 可填具体{TenantID}、organizations、common或consumers的说明正是对应 Azure 应用注册时不同 access type 所产生的授权端点差异。数据可信度治理rawData 存储与 disableEmailSync1.2.0返回并存储原始数据1.2.0 起getUserInfo的返回值中除了标准化的id、email、name外还包含 Graph 返回的完整原始 JSONsrc/index.tsreturn { id, email: conditional(!config.disableEmailSync mail), name: conditional(displayName), rawData, };原始数据同时经过 zod 的userInfoResponseGuard校验src/types.ts要求id必填、其余字段displayName、mail、userPrincipalName等允许为空。测试用例验证了响应缺少id时会抛出invalid_response错误src/index.test.ts。1.7.0disableEmailSync开关当前版本的核心变更1.7.0 是本 CHANGELOG 中最新的功能性变更commitc81931eab4也是理解整个连接器邮箱来源问题的一把钥匙。变更动机在 CHANGELOG 原文中已经交代The connector always synced themailattribute returned by Microsoft Graph to the user profile. This switch makes that configurable, matching the control the Azure OIDC SSO connector already offers. It is off by default, so existing connectors keep their current behavior.即该连接器此前总是把 Graph 返回的mail属性同步进用户资料此开关使该行为可配置与 Azure OIDC SSO 连接器已有的同类控制保持一致默认关闭存量连接器行为不变。README.md 进一步解释了为什么要做这个开关Microsoft Graph 返回mail属性但不报告其验证状态而mail是目录属性目录管理员可以将其设置为任意值——它的可信度只取决于来源目录本身。实现上有三处配合配置模型azureADConfigGuard新增可选布尔字段src/types.ts表单项控制台以Switch类型呈现默认值false并在 tooltip 中说明打开后邮箱地址仅保留在rawData中src/constant.ts行为分支getUserInfo中email: conditional(!config.disableEmailSync mail)即开关打开时返回对象不再携带email字段mail原值仍可通过rawData访问。单元测试对该行为做了双向验证默认配置下email等于 Graph 返回的mail值src/index.test.ts配置disableEmailSync: true后userInfo.email为undefined而rawData中仍完整保留mailsrc/index.test.ts。README 给出了实际运维建议当应用注册允许来自你不可控目录的登录access type 不是仅本组织目录或 Tenant ID 为organizations/common/consumers时应考虑开启该开关改由其他来源提供用户邮箱。工程基线升级Node 引擎、构建工具与依赖联动CHANGELOG 中的非功能条目同样有源码佐证Node 引擎演进1.1.0 从 Node 18 切到 20 LTS且 CHANGELOG 特别注明因 Logto 以 Docker 镜像交付对用户不具破坏性故标记为 minor1.5.0 再次提升到^22.14.0。当前 package.json 中的engines.node即为^22.14.0开发依赖types/node也同步为^22.14.0。构建工具切换1.4.0 说明部分包改用tsup构建以加快构建速度且不影响功能用 minor 版本号提醒使用者。当前 package.json 中build脚本为tsup、dev为tsup --watch测试脚本为vitest run src。依赖联动1.0.1 至 1.6.5 间的多数 Patch 版本仅因logto/connector-kit升级而发布如 1.4.1 的依赖安全升级。当前包依赖azure/msal-node^2.0.0、got^14.0.0与zod3.24.3见 package.json。当前版本的完整配置模型综合 src/types.ts 的 zod schema 与 src/constant.ts 的表单定义1.7.0 版本的配置项如下与 README.md 的配置表格一致配置项类型必填说明clientIdstring是Azure Portal 中应用的 Application (client) IDclientSecretstring是应用客户端密钥仅在创建时完整展示一次cloudInstancestring是认证云实例端点默认https://login.microsoftonline.com表单项内置 defaultValuetenantIdstring是具体 TenantID或organizations/common/consumers与 Azure 应用 access type 对应promptsstring[]否none/login/consent/select_account多值以空格拼接进授权 URLscopesstring?否空格分隔的 scope 列表缺省为User.ReaddisableEmailSyncboolean?否默认false开启后 Graphmail不再写入用户资料仅保留在rawData从代码结构看配置在每次getAuthorizationUri/getUserInfo调用时都会经validateConfig(config, azureADConfigGuard)重新校验非法配置会抛出ConnectorErrorGraph 请求超时为 5 秒defaultTimeout见 src/constant.tsGraph 返回 401 时映射为SocialAccessTokenInvalid错误码src/index.ts。如何在仓库中验证与运行由于仓库为只读研究环境以下仅为查看与运行方式不建议在仓库内做修改查看当前版本与依赖package.json阅读完整变更历史CHANGELOG.md阅读面向集成者的操作指南Azure Portal 应用注册、回调 URI${your_logto_endpoint}/callback/${connector_id}的设置、各配置项的获取位置README.md本地运行单元测试在该包目录下执行pnpm test即vitest run src可复现上述disableEmailSync、Graph 响应校验等行为的测试断言package.json。小结回看整份 CHANGELOGlogto/connector-azuread的版本史清晰地呈现了一个社交连接器从能用走向可控、可信的过程1.3.0/1.4.2/1.6.0 三步放宽了授权请求的自定义能力prompt、静态 scopes、运行时 scope1.2.0 与 1.7.0 则处理更深层的问题——外部身份数据进入 Logto 用户资料时的可信度边界disableEmailSync正是这条线上与 Azure OIDC SSO 连接器对齐的关键补齐。对使用者而言升级路径平滑1.7.0 的新开关默认关闭存量行为不变对阅读源码者而言src/types.ts的 zod schema、src/constant.ts的表单定义与src/index.test.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 Azure AD 连接器版本演进解析：prompt、scopes 与 disableEmailSync 的设计与实现
Logto Azure AD 连接器版本演进解析prompt、scopes 与 disableEmailSync 的设计与实现【免费下载链接】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本文以packages/connectors/connector-azuread/CHANGELOG.md为主线梳理 Logto 官方 Microsoft Azure AD 社交连接器logto/connector-azuread从 1.0.1 到 1.7.0 的完整版本演进。结合该包的源码src/index.ts、src/types.ts、src/constant.ts与测试用例逐项解释每个版本变更背后的实现方式——尤其是最新的disableEmailSync开关如何切断 Microsoft Graphmail属性与用户资料的绑定帮助你理解 Logto 社交连接器的配置语义、版本升级路径与源码级验证手段。连接器定位与代码结构Logto 的 Azure AD 连接器是一个Social类型连接器元数据 ID 为azuread-universaltarget 为azuread它基于azure/msal-node的ConfidentialClientApplication实现 OAuth 2.0 授权码流程并在拿到 access token 后调用 Microsoft Graph 的/v1.0/me接口获取用户资料。从 CHANGELOG 可以看出该包的核心依赖始终是logto/connector-kit连接器的公共类型与工具库版本演进中有大量条目是跟随 connector-kit 升级而触发的依赖更新。包的目录结构与关键文件如下文件职责src/index.ts连接器主体getAuthorizationUri、getAccessToken、getUserInfo三大方法src/types.ts基于 zod 的配置校验azureADConfigGuard与 Graph 响应校验src/constant.ts默认元数据、控制台表单项formItems、默认 scope、Graph 端点与超时src/index.test.ts基于 vitest nock 的单元测试覆盖 Graph 响应校验与disableEmailSync行为package.json版本1.7.0、依赖声明、tsup构建脚本、Node 引擎要求README.md面向使用者的集成指南Azure Portal 配置 Logto 侧配置说明版本演进总览以下是 CHANGELOG.md 记录的完整版本历史可整体概括为三条演进线认证行为可配置化prompt → scopes → 自定义 scope、数据可信度治理rawData 存储 → disableEmailSync、工程基线升级Node LTS 与构建工具版本类型变更摘要1.7.0Minor新增disableEmailSync开关使 Graphmail属性同步到用户资料的行为可配置commitc81931eab41.6.5Patch依赖更新logto/connector-kit升级至 5.1.01.6.4Patch依赖更新connector-kit 5.0.11.6.3Patch依赖更新connector-kit 5.0.01.6.2Patch依赖更新connector-kit 4.7.01.6.1Patch依赖更新connector-kit 4.6.01.6.0MinorgetAuthorizationUri方法支持自定义scope参数commit34964af461.5.0MinorNode 版本要求提升到^22.14.01.4.2Patch新增scopes配置字段1.4.1Patch依赖安全升级1.4.0Minor构建工具切换到tsup以 Minor 版本提醒使用者注意1.3.0Minor支持prompt配置1.2.0Minor返回并存储社交连接器原始数据rawData同时重写 Microsoft 集成指南专门澄清不同 access type 对应的 Tenant ID1.1.0Minor引擎要求切换为 Node 20 LTS因 Logto 以 Docker 镜像交付对用户不具破坏性1.0.1Patch依赖更新connector-kit 2.0.0可以看到从 1.6.1 到 1.6.5 连续多个 Patch 版本都没有本包自身的功能变更仅是跟随 connector-kit 的依赖升级发布。这种版本跟随模式说明连接器包与工具包之间保持着严格的版本联动。认证行为可配置化从 prompt 到 scope 的三步演进1.3.0支持prompt配置prompt是 OIDC 授权请求参数用于控制用户交互行为。连接器的prompts配置项在 src/constant.ts 中定义为一个MultiSelect表单项其可选值来自 connector-kit 导出的OidcPrompt枚举// packages/toolkit/connector-kit/src/types/social.ts export enum OidcPrompt { None none, Login login, Consent consent, SelectAccount select_account, }在 src/index.ts 中多个 prompt 会以空格拼接后写入授权 URL...conditional(prompts prompts.length 0 { prompt: prompts.join( ) }),配置校验则复用 connector-kit 的oidcPromptsGuard见 src/types.ts。各取值的语义在 README.md 中有明确说明promptlogin强制用户重新输入凭据、promptnone要求静默完成 SSO否则返回interaction_required错误、promptconsent触发授权同意对话框、promptselect_account打断 SSO 让用户选择账号。1.4.2新增scopes配置字段1.4.2 在配置模型中加入了可选的scopes字段src/types.tsscopes: z.string().optional()。它接受空格分隔的 scope 列表控制台表单中对应一个Text输入框placeholder 为scope1 scope2src/constant.ts。不填时使用默认值User.Read定义在 src/constant.ts。1.6.0getAuthorizationUri支持运行时自定义 scope1.6.0 的变更把scope从静态配置扩展为动态参数getAuthorizationUri方法的入参新增可选的scope字段。从 src/index.ts 的实现可以看到两条路径的取舍逻辑——若调用方显式传入scope则直接按其拆分结果使用否则回退为默认 scope 配置项 scope 去重合并const defaultAuthCodeUrlParameters: AuthorizationUrlRequest { scopes: scope ? scope.split( ) : deduplicate([...defaultScopes, ...(scopes?.split( ) ?? [])]), state, redirectUri, ...conditional(prompts prompts.length 0 { prompt: prompts.join( ) }), };这一签名来源于 connector-kit 的公共类型定义GetAuthorizationUripayload 中包含scope?: string见 packages/toolkit/connector-kit/src/types/social.ts意味着该能力由工具包统一约定、各社交连接器共同实现为不同登录场景请求不同授权范围提供了更灵活的空间。授权 URL 的构造过程本身依赖 MSAL连接器以cloudInstance tenantId拼接出 authoritysrc/index.ts因此 README 中Tenant ID 可填具体{TenantID}、organizations、common或consumers的说明正是对应 Azure 应用注册时不同 access type 所产生的授权端点差异。数据可信度治理rawData 存储与 disableEmailSync1.2.0返回并存储原始数据1.2.0 起getUserInfo的返回值中除了标准化的id、email、name外还包含 Graph 返回的完整原始 JSONsrc/index.tsreturn { id, email: conditional(!config.disableEmailSync mail), name: conditional(displayName), rawData, };原始数据同时经过 zod 的userInfoResponseGuard校验src/types.ts要求id必填、其余字段displayName、mail、userPrincipalName等允许为空。测试用例验证了响应缺少id时会抛出invalid_response错误src/index.test.ts。1.7.0disableEmailSync开关当前版本的核心变更1.7.0 是本 CHANGELOG 中最新的功能性变更commitc81931eab4也是理解整个连接器邮箱来源问题的一把钥匙。变更动机在 CHANGELOG 原文中已经交代The connector always synced themailattribute returned by Microsoft Graph to the user profile. This switch makes that configurable, matching the control the Azure OIDC SSO connector already offers. It is off by default, so existing connectors keep their current behavior.即该连接器此前总是把 Graph 返回的mail属性同步进用户资料此开关使该行为可配置与 Azure OIDC SSO 连接器已有的同类控制保持一致默认关闭存量连接器行为不变。README.md 进一步解释了为什么要做这个开关Microsoft Graph 返回mail属性但不报告其验证状态而mail是目录属性目录管理员可以将其设置为任意值——它的可信度只取决于来源目录本身。实现上有三处配合配置模型azureADConfigGuard新增可选布尔字段src/types.ts表单项控制台以Switch类型呈现默认值false并在 tooltip 中说明打开后邮箱地址仅保留在rawData中src/constant.ts行为分支getUserInfo中email: conditional(!config.disableEmailSync mail)即开关打开时返回对象不再携带email字段mail原值仍可通过rawData访问。单元测试对该行为做了双向验证默认配置下email等于 Graph 返回的mail值src/index.test.ts配置disableEmailSync: true后userInfo.email为undefined而rawData中仍完整保留mailsrc/index.test.ts。README 给出了实际运维建议当应用注册允许来自你不可控目录的登录access type 不是仅本组织目录或 Tenant ID 为organizations/common/consumers时应考虑开启该开关改由其他来源提供用户邮箱。工程基线升级Node 引擎、构建工具与依赖联动CHANGELOG 中的非功能条目同样有源码佐证Node 引擎演进1.1.0 从 Node 18 切到 20 LTS且 CHANGELOG 特别注明因 Logto 以 Docker 镜像交付对用户不具破坏性故标记为 minor1.5.0 再次提升到^22.14.0。当前 package.json 中的engines.node即为^22.14.0开发依赖types/node也同步为^22.14.0。构建工具切换1.4.0 说明部分包改用tsup构建以加快构建速度且不影响功能用 minor 版本号提醒使用者。当前 package.json 中build脚本为tsup、dev为tsup --watch测试脚本为vitest run src。依赖联动1.0.1 至 1.6.5 间的多数 Patch 版本仅因logto/connector-kit升级而发布如 1.4.1 的依赖安全升级。当前包依赖azure/msal-node^2.0.0、got^14.0.0与zod3.24.3见 package.json。当前版本的完整配置模型综合 src/types.ts 的 zod schema 与 src/constant.ts 的表单定义1.7.0 版本的配置项如下与 README.md 的配置表格一致配置项类型必填说明clientIdstring是Azure Portal 中应用的 Application (client) IDclientSecretstring是应用客户端密钥仅在创建时完整展示一次cloudInstancestring是认证云实例端点默认https://login.microsoftonline.com表单项内置 defaultValuetenantIdstring是具体 TenantID或organizations/common/consumers与 Azure 应用 access type 对应promptsstring[]否none/login/consent/select_account多值以空格拼接进授权 URLscopesstring?否空格分隔的 scope 列表缺省为User.ReaddisableEmailSyncboolean?否默认false开启后 Graphmail不再写入用户资料仅保留在rawData从代码结构看配置在每次getAuthorizationUri/getUserInfo调用时都会经validateConfig(config, azureADConfigGuard)重新校验非法配置会抛出ConnectorErrorGraph 请求超时为 5 秒defaultTimeout见 src/constant.tsGraph 返回 401 时映射为SocialAccessTokenInvalid错误码src/index.ts。如何在仓库中验证与运行由于仓库为只读研究环境以下仅为查看与运行方式不建议在仓库内做修改查看当前版本与依赖package.json阅读完整变更历史CHANGELOG.md阅读面向集成者的操作指南Azure Portal 应用注册、回调 URI${your_logto_endpoint}/callback/${connector_id}的设置、各配置项的获取位置README.md本地运行单元测试在该包目录下执行pnpm test即vitest run src可复现上述disableEmailSync、Graph 响应校验等行为的测试断言package.json。小结回看整份 CHANGELOGlogto/connector-azuread的版本史清晰地呈现了一个社交连接器从能用走向可控、可信的过程1.3.0/1.4.2/1.6.0 三步放宽了授权请求的自定义能力prompt、静态 scopes、运行时 scope1.2.0 与 1.7.0 则处理更深层的问题——外部身份数据进入 Logto 用户资料时的可信度边界disableEmailSync正是这条线上与 Azure OIDC SSO 连接器对齐的关键补齐。对使用者而言升级路径平滑1.7.0 的新开关默认关闭存量行为不变对阅读源码者而言src/types.ts的 zod schema、src/constant.ts的表单定义与src/index.test.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），仅供参考