OpenMetadata SAML SSO 客户端配置完整指南IdP/SP 参数、安全策略与底层实现解析【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata本文以 OpenMetadata 官方 SAML SSO 客户端配置文档samlSSOClientConfig.md为核心骨架系统讲解如何在 OpenMetadata 中接入 SAML 身份提供方IdP覆盖 SP/IdP 两侧全部配置字段、安全与授权参数并结合仓库内的 JSON Schema、服务端实现与 YAML 配置模板进行源码级验证。读完本文你将能够独立完成 ADFS、Okta、Azure AD 等 SAML IdP 与 OpenMetadata 的对接、签名与加密策略配置以及管理员与域名访问控制。一、SAML SSO 在 OpenMetadata 中的定位SAMLSecurity Assertion Markup LanguageSSO 允许用户使用企业身份提供方登录 OpenMetadata典型 IdP 包括 Active Directory Federation ServicesADFS、Shibboleth、Okta、Azure AD 等。在 OpenMetadata 中SAML 是 Settings → SSO 认证配置中可选的一种 Auth Provider与 Google、Azure、Okta、Auth0、LDAP、Custom OIDC 等并列。UI 侧通过 SSODocPanel.constants.ts 中的PROVIDER_FILE_MAP将AuthProvider.Saml映射到本文档对应的说明面板用户在配置表单中填写的字段即对应后端SamlSSOClientConfig结构。SAML 对接本质上是两个元数据的双向交换服务提供方SP即 OpenMetadata向 IdP 提供 SP Entity ID 与 Assertion Consumer ServiceACSURL身份提供方IdP向 OpenMetadata 提供 IdP Entity ID、SSO 登录 URL 与 X509 证书。这两组信息一旦任一侧不匹配整个登录链路都会失败因此精确复制是配置的第一要义。二、配置工作流总览官方文档给出了四步标准流程这里结合 UI 表单与后端配置展开获取 OpenMetadata 服务提供方信息从配置表单读取自动生成的SP Entity ID与ACS URL只读字段由 OpenMetadata URL 自动推导不可修改。配置身份提供方在 IdPADFS、Okta、Azure AD 等中新建 SAML 应用/服务将 SP Entity ID 粘贴为 Entity ID / Application ID将 ACS URL 粘贴为 Reply URL / Callback URL / Consumer URL并配置用户属性与 claims 映射。获取身份提供方信息从 IdP 管理后台取得 IdP Entity ID、SSO Login URL 与 IdP X509 证书。完成 OpenMetadata 配置在表单中填入上述 IdP 信息配置安全选项签名、加密并保存。重要约束SP Entity ID 与 ACS URL 基于你的 OpenMetadata URL 自动生成且不可更改IdP 中必须原样使用这两个值SAML 才能正常工作。后端 Schema samlSSOClientConfig.json 明确要求idpIdP 配置与spSP 配置两个对象为必填其中idp必须包含entityId与ssoLoginUrlsp必须包含entityId、acs与callback。这意味着一次完整的 SAML 对接IdP 与 SP 两侧信息缺一不可。三、启用自助注册Enable Self Signup项目说明字段 IDenableSelfSignup定义是否允许用户在首次 SAML 登录时自动创建账户选项Enabled / Disabled默认值视部署配置而定示例Enabled该开关控制新 SAML 用户是自动加入还是需要人工审批。从服务端实现看SamlAuthServletHandler.java 的getOrCreateUser方法在用户不存在时检查authConfig.getEnableSelfSignup()开启则自动创建用户并标记邮箱已验证关闭则抛出AuthenticationException(User not found and self-signup is disabled)。因此若希望严格控制访问、仅允许预置用户登录应关闭该选项否则任何能通过 IdP 认证的人都可能自动获得账户。四、身份提供方IdP配置4.1 IdP Entity IDentityId定义身份提供方的唯一标识符。示例https://adfs.company.com/adfs/services/trust作用SAML 消息使用它来识别 IdP。注意必须与 IdP 侧配置完全一致。Schema 中对idp.entityId的描述为 Identity Provider Entity ID usually same as the SSO login URL即多数情况下它与 SSO 登录 URL 相同ADFS 场景尤为典型。同时 Schema 保留了一个已废弃字段authorityUrlAuthority URL (deprecated, use entityId instead)说明该字段是历史遗留新配置一律使用entityId。4.2 SSO Login URLssoLoginUrl定义用户被重定向到 IdP 进行认证的 URL。示例https://adfs.company.com/adfs/ls/作用认证请求AuthnRequest被发送到该地址。注意通常由 IdP 管理员提供。该 URL 在服务端被映射为 one-login 库的IDP_SINGLE_SIGN_ON_SERVICE_URL_PROPERTY_KEY绑定方式固定为urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect即 OpenMetadata 通过 HTTP-Redirect 绑定将 SAML 认证请求发往该地址见 SamlSettingsHolder.java。4.3 IdP X509 证书idpX509Certificate定义用于校验 IdP 发来 SAML 断言的公钥证书。示例-----BEGIN CERTIFICATE-----\nMIIC...certificate content...\n-----END CERTIFICATE-----作用确保 SAML 断言确实来自你的 IdP防止伪造。注意事项必须是实际证书内容而不是证书指纹fingerprint必须包含BEGIN/END标记行支持多行证书内容。Schema 中该字段类型为string且format: password表明它在存储与展示时按敏感信息处理。仓库中还有专门的 SamlValidator.java 负责校验证书数据包含validateX509Certificate等方法从源码结构看配置保存阶段会先做证书格式与合法性校验避免非法证书进入运行时。4.4 Name ID FormatnameId定义SAML NameID 元素中标识用户所使用的格式。默认值urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress示例urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress作用决定 SAML 断言中如何标识用户。注意邮箱格式最常见且推荐使用。注意一个细节差异UI 文档给出的默认值是 SAML 1.1 的 emailAddress URI而 JSON Schema samlSSOClientConfig.json 中idp.nameId的默认值是 SAML 2.0 版本urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress两者语义等价均为邮箱格式实际生效值以你保存的配置为准。NameID 的取值直接决定后续用户名的推导方式见下文授权配置。五、服务提供方SP配置5.1 SP Entity IDentityId定义OpenMetadata 作为服务提供方的唯一标识符。示例https://openmetadata.company.com自动生成根据 OpenMetadata 部署 URL 自动填充。作用IdP 在 SAML 交换中据此识别 OpenMetadata。注意只读字段不可编辑复制该值并粘贴为 IdP 配置中的 Entity ID或 Application ID必须与 IdP 受信任应用列表中的值完全一致。在conf/openmetadata.yaml中SP Entity ID 的默认模板为http://localhost:8585/api/v1/saml/metadata对应环境变量SAML_SP_ENTITY_ID这也是 OpenMetadata 对外暴露 SAML 元数据Metadata的端点地址IdP 常通过导入该元数据端点自动完成大部分 SP 侧配置。5.2 Assertion Consumer ServiceACSURLacs定义IdP 完成认证后回传 SAML 断言的地址。示例https://openmetadata.company.com/callback自动生成根据 OpenMetadata 部署 URL 自动填充。作用登录后 SAML 响应Response被 POST 到该地址。注意只读字段不可编辑复制后粘贴为 IdP 中的 ACS URL也叫 Reply URL、Callback URL 或 Consumer URL格式恒为{your-domain}/callback必须在 IdP 配置中精确注册。YAML 模板中的默认值为http://localhost:8585/api/v1/saml/acsSAML_SP_ACSSP 侧接收 IdP POST 的绑定方式固定为 HTTP-POSTurn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST。另外 Schema 的sp对象中还定义了一个必填的callback字段默认http://localhost:8585/saml/callback环境变量SAML_SP_CALLBACK它在服务端被用作登录完成后的 RelayState 回跳地址——即用户完成认证后被浏览器重定向回 OpenMetadata 前端的地址这也解释了为什么 ACSAPI 端与 callback前端端是两条不同的 URL。5.3 SP X509 证书spX509Certificate定义OpenMetadata服务提供方的公钥证书。示例-----BEGIN CERTIFICATE-----\nMIIC...certificate content...\n-----END CERTIFICATE-----作用供 IdP 校验来自 OpenMetadata 的已签名 SAML 请求。注意仅在启用 SAML 请求签名时必需。5.4 SP 私钥spPrivateKey定义用于签名与加密的私钥仅限 SP 侧。示例-----BEGIN PRIVATE KEY-----\nMIIE...private key content...\n-----END PRIVATE KEY-----作用用于对 SAML 请求签名、解密加密断言。注意妥善保管并加密存储启用签名或加密功能时必需。Schema 中两者均标注为format: password。服务端 SamlSettingsHolder.java 对 SP 凭据加载有两套途径一是通过keyStoreFilePathkeyStoreAliaskeyStorePassword从 JKS 密钥库加载二是直接使用spX509CertificatespPrivateKey字符串当签名或断言加密被启用时两者必须至少提供一套否则直接抛出IllegalArgumentException提示 Either Specify (KeyStoreFilePath, KeyStoreAlias and KeyStorePassword) or (Sp X509 Certificate and Private Key) as one of both is mandatory.。六、安全配置Security Configuration6.1 严格模式Strict ModestrictMode定义仅在相关开关置位时接受合法签名与加密的断言。默认值false示例true作用通过强制签名与加密校验提升安全性。注意生产环境建议开启。6.2 Token 有效期秒Token ValiditytokenValidity定义SAML 响应生成的 OpenMetadata JWT 有效期秒。默认值36001 小时最小值1 秒示例72002 小时作用控制用户在 SAML 认证后的登录时长。注意控制的是 OpenMetadata JWT 令牌生命周期而非 SAML 断言本身的生命周期。Schema 对该字段的约束为integer、minimum: 1、default: 3600。服务端SamlSettingsHolder.getTokenValidity()会动态读取该配置并经TokenValidityResolver.resolveOrDefault解析若配置非法非正数则回退到默认值并记录警告日志。该 JWT 在SamlAuthServletHandler.generateJwtToken中通过JWTTokenGenerator生成并写入用户会话。6.3 发送签名认证请求Send Signed Auth RequestsendSignedAuthRequest定义是否对发送给 IdP 的认证请求签名。默认值false示例true作用确保请求确实来自 OpenMetadata防止请求伪造。注意需要配置 SP 私钥。6.4 签名 SP 元数据Sign SP MetadatasignSpMetadata定义是否对服务提供方元数据签名。默认值false示例true作用保证与 IdP 交换的元数据完整性。注意生产环境推荐开启。6.5 要求断言已签名Want Assertions SignedwantAssertionsSigned定义要求 IdP 对 SAML 断言进行数字签名。默认值false示例true作用确保断言未被篡改。注意出于安全强烈建议开启。6.6 要求消息已签名Want Messages SignedwantMessagesSigned定义要求 IdP 对 SAML 消息整体进行数字签名。默认值false示例true作用确保整个 SAML 消息真实可信。注意在断言签名之外提供额外一层安全。6.7 Schema 中补充的安全字段除 UI 文档列出的六项外JSON Schema samlSSOClientConfig.json 还定义了以下安全项均可在conf/openmetadata.yaml中通过环境变量配置字段环境变量默认值说明validateXmlSAML_VALIDATE_XMLfalse严格模式下是否校验 XML 格式sendEncryptedNameIdSAML_SEND_ENCRYPTED_NAME_IDfalseSP 发送请求时是否加密 NameIDwantAssertionEncryptedSAML_WANT_ASSERTION_ENCRYPTEDfalseSP 要求收到的断言已加密keyStoreFilePathSAML_KEYSTORE_FILE_PATH空JKS 密钥库文件路径keyStoreAliasSAML_KEYSTORE_ALIAS空密钥库别名keyStorePasswordSAML_KEYSTORE_PASSWORD空密钥库密码format: password服务端在构建 one-login 设置时还会固定使用 RSA-SHA256 签名算法http://www.w3.org/2001/04/xmldsig-more#rsa-sha256与 SHA-256 摘要算法并将SECURITY_REQUESTED_AUTHNCONTEXTCOMPARISON设为exact、NameID 加密设为false、SP 唯一 ID 前缀设为OPENMETADATA_。这些细节说明 OpenMetadata 的 SAML 实现基于开源 one-login SAML 库com.onelogin.saml2配置面板上的选项最终都会映射为该库的Saml2Settings参数。七、高级配置调试模式Debug ModedebugMode定义开启 SAML 认证过程的调试日志。默认值false示例true作用帮助排查 SAML 配置问题。注意仅在故障排查时开启生产环境关闭以保证安全与性能。该值在服务端被映射为 one-login 库的DEBUG_PROPERTY_KEY开启后 SAML 库会输出更详细的认证过程日志是定位「配置完成后无法登录」类问题的第一把钥匙。Schema 还额外定义了samlDisplayNameAttributes有序的 SAML 属性名列表用于提取用户显示名按顺序取第一个存在的属性为空时使用常见的 OIDC/SAML 属性名兜底——如果你的 IdP 发送的显示名属性不在默认列表中可通过该字段定制映射。八、授权配置Authorizer Configuration以下设置控制 OpenMetadata 全局的授权与访问控制对所有认证提供方统一生效即不仅限于 SAML。这些字段在conf/openmetadata.yaml的authorizerConfiguration段中配置。8.1 管理员主体Admin PrincipalsadminPrincipals定义拥有 OpenMetadata 管理员权限的用户主体列表。示例[john.doe, jane.admin, admin]作用这些用户拥有完整管理权限。注意使用用户名不是完整邮箱地址至少需要一个管理员主体对 SAML 而言用户名由 NameID 推导而来若为邮箱格式则取之前的部分。该推导逻辑与 SamlAuthServletHandler.java 的回调处理一致nameId含时用户名取前部分、邮箱用整个 NameID不含时用户名就是 NameID邮箱拼接为{username}{principalDomain}。getAdminPrincipals()读取authorizerConfig.getAdminPrincipals()并在用户创建/更新时同步isAdmin状态因此即使 IdP 返回的 NameID 是邮箱也要用前的用户名部分来声明管理员。8.2 主体域Principal DomainprincipalDomain定义用户主体的默认域。示例company.com作用当只提供用户名时用于构造完整用户主体。注意通常是你组织的域名。对应 YAML 环境变量为AUTHORIZER_PRINCIPAL_DOMAIN默认值open-metadata.org。8.3 强制主体域Enforce Principal DomainenforcePrincipalDomain定义是否强制所有用户都属于主体域。默认值false示例true作用通过限制特定域用户访问增加一层安全。注意开启后只有来自配置的主体域的用户才能访问 OpenMetadata。8.4 允许的域Allowed DomainsallowedDomains定义允许访问 OpenMetadata 的邮箱域列表。示例[company.com, partner.com]作用细粒度控制哪些邮箱域可通过 SAML 认证。注意与enforcePrincipalDomain配合使用当enforcePrincipalDomain开启时只有邮箱地址来自这些域的用户才能访问若只有一个域可留空或仅使用principalDomain多域组织使用该字段。对应 YAML 环境变量为AUTHORIZER_ALLOWED_DOMAINS默认[]与AUTHORIZER_ENFORCE_PRINCIPAL_DOMAIN默认false。九、配置文件方式YAML 环境变量映射UI 表单保存的配置最终落在数据库中但 OpenMetadata 同样支持通过conf/openmetadata.yaml以环境变量方式预置 SAML 配置适合容器化与 Helm 部署。该文件 openmetadata.yaml 中authenticationConfiguration.samlConfiguration段的完整映射如下authenticationConfiguration: provider: saml # 认证提供方切换为 saml samlConfiguration: debugMode: ${SAML_DEBUG_MODE:-false} idp: entityId: ${SAML_IDP_ENTITY_ID:-} ssoLoginUrl: ${SAML_IDP_SSO_LOGIN_URL:-} idpX509Certificate: ${SAML_IDP_CERTIFICATE:-} nameId: ${SAML_IDP_NAME_ID:-urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress} sp: entityId: ${SAML_SP_ENTITY_ID:-http://localhost:8585/api/v1/saml/metadata} acs: ${SAML_SP_ACS:-http://localhost:8585/api/v1/saml/acs} spX509Certificate: ${SAML_SP_CERTIFICATE:-} spPrivateKey: ${SAML_SP_PRIVATE_KEY:-} callback: ${SAML_SP_CALLBACK:-http://localhost:8585/saml/callback} security: strictMode: ${SAML_STRICT_MODE:-false} validateXml: ${SAML_VALIDATE_XML:-false} tokenValidity: ${SAML_SP_TOKEN_VALIDITY:-3600} sendEncryptedNameId: ${SAML_SEND_ENCRYPTED_NAME_ID:-false} sendSignedAuthRequest: ${SAML_SEND_SIGNED_AUTH_REQUEST:-false} signSpMetadata: ${SAML_SIGNED_SP_METADATA:-false} wantMessagesSigned: ${SAML_WANT_MESSAGE_SIGNED:-false} wantAssertionsSigned: ${SAML_WANT_ASSERTION_SIGNED:-false} wantAssertionEncrypted: ${SAML_WANT_ASSERTION_ENCRYPTED:-false} keyStoreFilePath: ${SAML_KEYSTORE_FILE_PATH:-} keyStoreAlias: ${SAML_KEYSTORE_ALIAS:-} keyStorePassword: ${SAML_KEYSTORE_PASSWORD:-} authorizerConfiguration: adminPrincipals: ${AUTHORIZER_ADMIN_PRINCIPALS:-[admin]} principalDomain: ${AUTHORIZER_PRINCIPAL_DOMAIN:-open-metadata.org} allowedDomains: ${AUTHORIZER_ALLOWED_DOMAINS:-[]} enforcePrincipalDomain: ${AUTHORIZER_ENFORCE_PRINCIPAL_DOMAIN:-false}可以看到SP Entity ID 与 ACS 的默认值基于localhost:8585生成生产环境必须通过SAML_SP_ENTITY_ID、SAML_SP_ACS、SAML_SP_CALLBACK覆盖为你实际的 OpenMetadata 域名且与 IdP 侧注册的值严格一致。十、登录链路从重定向到 JWT 的源码级原理结合 SamlAuthServletHandler.java一次完整 SAML 登录的时序为发起登录handleLogin用户点击登录后服务端校验回跳 URI 并创建 Pending Session用SamlSettingsHolder.getSaml2Settings()构造 one-loginAuth对象调用auth.login(...)将用户重定向到 IdP 的 SSO Login URL。该 URL 与绑定方式均来自第五节所述的 IdP 配置。IdP 认证用户在 IdP 完成认证后IdP 将 SAML Response POST 到 ACS URLHTTP-POST 绑定。回调处理handleCallback服务端调用auth.processResponse()解析并校验响应auth.isAuthenticated()为假或存在错误时拒绝登录随后从响应中取 NameID 推导用户名与邮箱提取显示名支持samlDisplayNameAttributes定制映射按需提取团队属性jwtTeamClaimMapping再调用getOrCreateUser完成用户创建或属性同步。签发令牌生成 Refresh Token 并激活会话最终通过generateJwtToken按tokenValidity生成 JWT携带 token 重定向回前端 callback。刷新与会话handleRefresh / handleLogout支持令牌轮换Refresh Token Rotation与 SAML Single LogoutSLO通过auth.logout()重定向 IdP 注销失败时回退为仅清理本地会话。其中所有 IdP/SP/安全参数的装载集中在 SamlSettingsHolder.java 的initDefaultSettings它把表单中的每一项idp.entityId、idp.ssoLoginUrl、idp.idpX509Certificate、sp.entityId、sp.acs、security.*等逐一映射为 one-loginSettingsBuilder的属性并构建Saml2Settings单例。因此UI 表单、YAML 配置与运行时 SAML 行为三者完全一一对应。十一、常见问题与排障建议登录跳转 IdP 后报错 / 无法回跳优先核对 ACS URL 与 SP Entity ID 是否与 IdP 注册值完全一致注意{domain}前缀与/api/v1/saml/acs路径以及SAML_SP_CALLBACK是否为可访问的前端地址。断言校验失败确认idpX509Certificate粘贴的是完整证书含 BEGIN/END 行而非指纹若 IdP 轮换了证书需同步更新。签名/加密功能不生效启用sendSignedAuthRequest或wantAssertionEncrypted前必须同时提供 SP 私钥与证书或 JKS 密钥库三项否则服务端在初始化设置时直接抛异常。用户登录后没有管理员权限adminPrincipals需使用 NameID 推导出的用户名邮箱格式时取前部分不是完整邮箱。用户无法自动创建检查enableSelfSignup是否开启关闭时只有预置用户可登录。定位问题首选开启debugMode查看 SAML 库详细日志生产环境排障后务必关闭。如需进一步了解字段定义与服务端校验细节可查阅 samlSSOClientConfig.json字段类型、默认值与必填约束和 SamlValidator.java证书与配置合法性校验。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考