NocoBase SAML 2.0 单点登录认证器配置、字段映射与 Google Workspace 对接实战【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase本文基于 NocoBase 官方文档《认证SAML 2.0》及其 Google Workspace 配置示例整理完整覆盖 SAML 认证插件的激活、认证器配置项、可供映射的用户字段与优先级规则并给出以 Google Workspace 为 IdP 的端到端配置流程。读完后你能够独立完成 NocoBase 与第三方身份认证服务商IdP之间的 SAML 2.0 SSO 对接理解每个配置项在 SP/IdP 两侧分别对应什么以及登录成功后用户数据是如何匹配和落库的。一、插件定位谁在发起登录谁在签发断言NocoBase 的「认证SAML 2.0」插件遵循 SAML 2.0Security Assertion Markup Language 2.0协议标准实现用户使用第三方身份认证服务商IdP, Identity Provider提供的账号登录 NocoBase。从 SAML 协议的视角看对接双方角色是固定的SPService Provider即 NocoBase 应用。它不直接校验密码而是把用户重定向到 IdP 的 SSO 端点并信任 IdP 签回的断言Assertion。IdPIdentity Provider如 Google Workspace负责真正的身份认证并把携带用户属性email、姓名等的签名单向登录响应发回给 SP。理解这一角色划分后文档中所有配置项就能对号入座SSO URL、公钥、实体ID都是 IdP 侧提供的材料而 NocoBase 配置面板底部的「使用Usage」区域则反向给出 SP 侧需要交给 IdP 的材料SP Issuer / EntityID和ACS URL。关于插件本身的元信息可从插件目录文档docs/docs/cn/plugins/nocobase/plugin-auth-saml/index.md确认包名nocobase/plugin-auth-saml支持版本1.x、2.xbuiltIn: false、defaultEnabled: false即非内置插件默认未启用需要手动激活元信息中标注isFree: false、editionLevel: 2属于非免费专业版档位插件。另外从源码结构看当前开源仓库中并未包含plugin-auth-saml的实现代码packages/plugins/下无该目录它是随 NocoBase 专业版分发交付的但认证体系的数据基座在开源仓库中可以看到见文末「源码佐证」一节。二、激活插件与添加 SAML 认证器2.1 激活插件进入 NocoBase 的插件管理列表找到「认证SAML 2.0」并激活。激活后该插件会在「用户认证」插件管理页面中注册一种新的认证器类型。2.2 添加 SAML 认证进入插件设置 → 用户认证管理页面点击「添加」在下拉中选择SAML即创建一个新的 SAML 认证器随后进入配置表单。三、配置项逐项说明配置表单是整篇文档的核心。以下按文档中的字段逐项说明其含义与填写来源配置项说明来源SSO URL用于单点登录的网址即 SP 把用户重定向过去的 IdP 登录端点由 IdP 提供公钥 (Public Certificate)IdP 的 X.509 证书公钥NocoBase 用它验证返回断言的签名由 IdP 提供实体ID (IdP Issuer)可选。IdP 的 Issuer 标识用于校验断言来源由 IdP 提供http如果 NocoBase 应用运行在 http非 https协议下需勾选此项常见于本地开发/测试环境本地环境决定Use this field to bind the user用于和已有用户匹配绑定的字段可选择邮箱或用户名默认为邮箱。前提是 IdP 断言携带的用户信息中包含email或username字段NocoBase 侧选择Sign up automatically when the user does not exist当按绑定字段找不到可匹配的已有用户时是否自动创建新用户NocoBase 侧选择使用 (Usage)展示SP Issuer / EntityID与ACS URL用于复制并填写到 IdP 的相应配置中NocoBase 生成两点实操要点http勾选只针对协议而非功能。生产环境使用 https 时无需勾选本地 http 联调例如 Google Workspace 示例中「如果是在本地 http 测试勾选」才需要打开否则会因回调地址协议不匹配导致登录失败。「Usage」是双向对接的关键。NocoBase 只填写了 IdP 的三项信息还不够必须把 NocoBase 生成的SP Issuer / EntityID和ACS URL回传到 IdP 的「服务提供商详细信息」中IdP 才知道把登录成功响应发回给谁、发给哪个地址。ACSAssertion Consumer ServiceURL 即 SP 侧接收断言的回调端点。四、字段映射NocoBase 侧接受什么字段映射需要在 IdP 的配置平台上进行配置而不是在 NocoBase 侧配置可参考 Google Workspace 配置示例。NocoBase 可供映射的字段有email必填phone仅对 scope 支持phone的平台生效如阿里云、飞书nicknameusernamefirstNamelastName另有两条规则需要注意nameID无需映射。它是 SAML 协议本身携带的字段NocoBase 会将其作为该用户在此认证器下的唯一标识保存。新用户昵称的取值优先级为nicknamefirstName lastNameusernamenameID。也就是说 IdP 侧把哪几个属性映射进断言直接决定了自动注册出来的用户显示名长什么样。同时文档明确说明暂时不支持映射用户组织、角色。如果你的权限体系依赖组织/角色需要登录落地后再另行处理。五、实战示例对接 Google Workspace这一节完整继承官方示例文档docs/docs/cn/auth-verification/auth-saml/examples/google.md的操作脉络。5.1 第一步在 Google 管理控制台创建 SAML 应用在 Google 管理控制台的「应用 → Web 应用和移动应用」中创建应用并完成基础设置。5.2 第二步从 Google 复制 IdP 三元组应用设置完成后复制以下三项SSO 网址实体 IDEntity ID证书5.3 第三步在 NocoBase 新增认证器进入「插件设置 → 用户认证 → 添加 → SAML」按对应关系填写NocoBase 配置项填入内容SSO URLSSO 网址Public Certificate证书IdP IssuerEntity ID实体 IDhttp如果是在本地 http 测试勾选填写完成后从Usage区域复制SP Issuer / EntityID和ACS URL两个值。5.4 第四步在 Google 侧填写 SP 信息并开启签名回到 Google 控制台的服务提供商详细信息页面输入刚才复制的ACS 网址和实体 ID勾选已签署响应保证返回的登录响应带签名NocoBase 才能用公钥完成验签。随后在属性映射位置添加映射把 Google 的用户属性如邮箱、姓名等映射到 SAML 断言中使其落入上文第四节列出的 NocoBase 可映射字段。其中email必须映射nameID由 Google 自动提供。5.5 第五步验证登录访问 NocoBase 登录页面点击登录表单下方的第三方登录按钮发起 SAML 登录。浏览器会跳转到 Google 完成认证Google 再携带签名断言回跳到 NocoBase 的 ACS URLNocoBase 验签后按「绑定字段 → 匹配已有用户 / 自动注册新用户」的规则完成登录。六、源码佐证认证器配置落在哪张表虽然plugin-auth-saml的实现代码未随开源仓库发布但 SAML 认证器并非凭空存在它复用的是 NocoBase 开源认证体系中的认证器注册表。在 users-authenticators.ts 中定义了usersAuthenticators集合源码注释明确写道该集合用于存储各类认证器记录such as saml, oicd, oauth, sms, etc.即 SAML、OIDC、OAuth、短信等export default defineCollection({ dumpRules: { group: user, }, shared: true, migrationRules: [schema-only, overwrite], name: usersAuthenticators, dataCategory: business, model: UserAuthModel, ... });可以推断你在配置表单里填写的 SSO URL、公钥、绑定字段、自动注册开关等最终都会以 JSON 形式保存在这张表的记录中登录流程发起重定向时buildRedirectPath.ts 中也有针对 saml 类型认证器的处理分支。也就是说同一个认证器集合同时承载 SAML 与 OIDC、OAuth 等其他类型SAML 插件只是向这套框架注册了自己的表单与登录处理器。七、常见注意点小结绑定字段必须与断言内容一致选择「用户名」绑定则 IdP 必须映射出username默认邮箱则必须映射email否则登录时既匹配不到老用户也会因缺少email无法注册新用户。http勾选与否取决于 NocoBase 自身的访问协议与 IdP 无关。IdP 侧务必开启签名响应如 Google 的「已签署响应」NocoBase 依赖公钥验签来防伪造断言。组织与角色不可映射权限需另行管理。本插件非内置、默认关闭builtIn: false、defaultEnabled: false且按插件元信息属于非免费档位部署前请确认你的 NocoBase 版本支持 1.x、2.x与授权档位是否包含该插件。以上即 NocoBase SAML 2.0 认证的完整配置面NocoBase 侧负责「接」填 IdP 三元组 绑定字段 自动注册策略IdP 侧负责「发」填 ACS URL/Entity ID 属性映射 签名两侧对齐后即可完成一次可验证的 SSO 闭环。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NocoBase SAML 2.0 单点登录：认证器配置、字段映射与 Google Workspace 对接实战
NocoBase SAML 2.0 单点登录认证器配置、字段映射与 Google Workspace 对接实战【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase本文基于 NocoBase 官方文档《认证SAML 2.0》及其 Google Workspace 配置示例整理完整覆盖 SAML 认证插件的激活、认证器配置项、可供映射的用户字段与优先级规则并给出以 Google Workspace 为 IdP 的端到端配置流程。读完后你能够独立完成 NocoBase 与第三方身份认证服务商IdP之间的 SAML 2.0 SSO 对接理解每个配置项在 SP/IdP 两侧分别对应什么以及登录成功后用户数据是如何匹配和落库的。一、插件定位谁在发起登录谁在签发断言NocoBase 的「认证SAML 2.0」插件遵循 SAML 2.0Security Assertion Markup Language 2.0协议标准实现用户使用第三方身份认证服务商IdP, Identity Provider提供的账号登录 NocoBase。从 SAML 协议的视角看对接双方角色是固定的SPService Provider即 NocoBase 应用。它不直接校验密码而是把用户重定向到 IdP 的 SSO 端点并信任 IdP 签回的断言Assertion。IdPIdentity Provider如 Google Workspace负责真正的身份认证并把携带用户属性email、姓名等的签名单向登录响应发回给 SP。理解这一角色划分后文档中所有配置项就能对号入座SSO URL、公钥、实体ID都是 IdP 侧提供的材料而 NocoBase 配置面板底部的「使用Usage」区域则反向给出 SP 侧需要交给 IdP 的材料SP Issuer / EntityID和ACS URL。关于插件本身的元信息可从插件目录文档docs/docs/cn/plugins/nocobase/plugin-auth-saml/index.md确认包名nocobase/plugin-auth-saml支持版本1.x、2.xbuiltIn: false、defaultEnabled: false即非内置插件默认未启用需要手动激活元信息中标注isFree: false、editionLevel: 2属于非免费专业版档位插件。另外从源码结构看当前开源仓库中并未包含plugin-auth-saml的实现代码packages/plugins/下无该目录它是随 NocoBase 专业版分发交付的但认证体系的数据基座在开源仓库中可以看到见文末「源码佐证」一节。二、激活插件与添加 SAML 认证器2.1 激活插件进入 NocoBase 的插件管理列表找到「认证SAML 2.0」并激活。激活后该插件会在「用户认证」插件管理页面中注册一种新的认证器类型。2.2 添加 SAML 认证进入插件设置 → 用户认证管理页面点击「添加」在下拉中选择SAML即创建一个新的 SAML 认证器随后进入配置表单。三、配置项逐项说明配置表单是整篇文档的核心。以下按文档中的字段逐项说明其含义与填写来源配置项说明来源SSO URL用于单点登录的网址即 SP 把用户重定向过去的 IdP 登录端点由 IdP 提供公钥 (Public Certificate)IdP 的 X.509 证书公钥NocoBase 用它验证返回断言的签名由 IdP 提供实体ID (IdP Issuer)可选。IdP 的 Issuer 标识用于校验断言来源由 IdP 提供http如果 NocoBase 应用运行在 http非 https协议下需勾选此项常见于本地开发/测试环境本地环境决定Use this field to bind the user用于和已有用户匹配绑定的字段可选择邮箱或用户名默认为邮箱。前提是 IdP 断言携带的用户信息中包含email或username字段NocoBase 侧选择Sign up automatically when the user does not exist当按绑定字段找不到可匹配的已有用户时是否自动创建新用户NocoBase 侧选择使用 (Usage)展示SP Issuer / EntityID与ACS URL用于复制并填写到 IdP 的相应配置中NocoBase 生成两点实操要点http勾选只针对协议而非功能。生产环境使用 https 时无需勾选本地 http 联调例如 Google Workspace 示例中「如果是在本地 http 测试勾选」才需要打开否则会因回调地址协议不匹配导致登录失败。「Usage」是双向对接的关键。NocoBase 只填写了 IdP 的三项信息还不够必须把 NocoBase 生成的SP Issuer / EntityID和ACS URL回传到 IdP 的「服务提供商详细信息」中IdP 才知道把登录成功响应发回给谁、发给哪个地址。ACSAssertion Consumer ServiceURL 即 SP 侧接收断言的回调端点。四、字段映射NocoBase 侧接受什么字段映射需要在 IdP 的配置平台上进行配置而不是在 NocoBase 侧配置可参考 Google Workspace 配置示例。NocoBase 可供映射的字段有email必填phone仅对 scope 支持phone的平台生效如阿里云、飞书nicknameusernamefirstNamelastName另有两条规则需要注意nameID无需映射。它是 SAML 协议本身携带的字段NocoBase 会将其作为该用户在此认证器下的唯一标识保存。新用户昵称的取值优先级为nicknamefirstName lastNameusernamenameID。也就是说 IdP 侧把哪几个属性映射进断言直接决定了自动注册出来的用户显示名长什么样。同时文档明确说明暂时不支持映射用户组织、角色。如果你的权限体系依赖组织/角色需要登录落地后再另行处理。五、实战示例对接 Google Workspace这一节完整继承官方示例文档docs/docs/cn/auth-verification/auth-saml/examples/google.md的操作脉络。5.1 第一步在 Google 管理控制台创建 SAML 应用在 Google 管理控制台的「应用 → Web 应用和移动应用」中创建应用并完成基础设置。5.2 第二步从 Google 复制 IdP 三元组应用设置完成后复制以下三项SSO 网址实体 IDEntity ID证书5.3 第三步在 NocoBase 新增认证器进入「插件设置 → 用户认证 → 添加 → SAML」按对应关系填写NocoBase 配置项填入内容SSO URLSSO 网址Public Certificate证书IdP IssuerEntity ID实体 IDhttp如果是在本地 http 测试勾选填写完成后从Usage区域复制SP Issuer / EntityID和ACS URL两个值。5.4 第四步在 Google 侧填写 SP 信息并开启签名回到 Google 控制台的服务提供商详细信息页面输入刚才复制的ACS 网址和实体 ID勾选已签署响应保证返回的登录响应带签名NocoBase 才能用公钥完成验签。随后在属性映射位置添加映射把 Google 的用户属性如邮箱、姓名等映射到 SAML 断言中使其落入上文第四节列出的 NocoBase 可映射字段。其中email必须映射nameID由 Google 自动提供。5.5 第五步验证登录访问 NocoBase 登录页面点击登录表单下方的第三方登录按钮发起 SAML 登录。浏览器会跳转到 Google 完成认证Google 再携带签名断言回跳到 NocoBase 的 ACS URLNocoBase 验签后按「绑定字段 → 匹配已有用户 / 自动注册新用户」的规则完成登录。六、源码佐证认证器配置落在哪张表虽然plugin-auth-saml的实现代码未随开源仓库发布但 SAML 认证器并非凭空存在它复用的是 NocoBase 开源认证体系中的认证器注册表。在 users-authenticators.ts 中定义了usersAuthenticators集合源码注释明确写道该集合用于存储各类认证器记录such as saml, oicd, oauth, sms, etc.即 SAML、OIDC、OAuth、短信等export default defineCollection({ dumpRules: { group: user, }, shared: true, migrationRules: [schema-only, overwrite], name: usersAuthenticators, dataCategory: business, model: UserAuthModel, ... });可以推断你在配置表单里填写的 SSO URL、公钥、绑定字段、自动注册开关等最终都会以 JSON 形式保存在这张表的记录中登录流程发起重定向时buildRedirectPath.ts 中也有针对 saml 类型认证器的处理分支。也就是说同一个认证器集合同时承载 SAML 与 OIDC、OAuth 等其他类型SAML 插件只是向这套框架注册了自己的表单与登录处理器。七、常见注意点小结绑定字段必须与断言内容一致选择「用户名」绑定则 IdP 必须映射出username默认邮箱则必须映射email否则登录时既匹配不到老用户也会因缺少email无法注册新用户。http勾选与否取决于 NocoBase 自身的访问协议与 IdP 无关。IdP 侧务必开启签名响应如 Google 的「已签署响应」NocoBase 依赖公钥验签来防伪造断言。组织与角色不可映射权限需另行管理。本插件非内置、默认关闭builtIn: false、defaultEnabled: false且按插件元信息属于非免费档位部署前请确认你的 NocoBase 版本支持 1.x、2.x与授权档位是否包含该插件。以上即 NocoBase SAML 2.0 认证的完整配置面NocoBase 侧负责「接」填 IdP 三元组 绑定字段 自动注册策略IdP 侧负责「发」填 ACS URL/Entity ID 属性映射 签名两侧对齐后即可完成一次可验证的 SSO 闭环。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考