OpenMetadata 集成 Auth0 SSO 完整配置指南OAuth 2.0 / OIDC 认证参数逐项详解【免费下载链接】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/OpenMetadataAuth0 是业界常用的身份即服务IDaaS平台OpenMetadata 通过 OAuth 2.0 与 OpenID ConnectOIDC协议支持用户使用 Auth0 账户登录。本文以仓库中的 auth0SSOClientConfig.md 文档为骨架逐项拆解 OpenMetadata UI 中 Auth0 SSO 的每一个配置字段Authentication、OIDC、Authorizer 三大区块并结合 Auth0Validator.java 的校验源码、auth0SSOClientConfig.json 的 JSON Schema 以及 openmetadata.yaml 的环境变量映射说明每个参数的作用、默认值、配置位置与底层校验逻辑。读完本文你将能独立完成从 Auth0 应用注册、OpenMetadata 侧参数填写到团队自动分配、管理员授权的端到端配置并理解常见认证失败的根本原因。一、整体认识Auth0 SSO 在 OpenMetadata 中的位置OpenMetadata 的认证体系分为authenticationConfiguration认证配置与authorizerConfiguration授权配置两大部分。在 authConfig.json 中auth0是provider的可选值之一对应$ref指向 auth0SSOClientConfig.json后者定义了三项必填属性clientIdAuth0 客户端 IDsecretKeyAuth0 客户端密钥格式标注为passworddomainAuth0 域名。UI 侧的auth0SSOClientConfig.md正是该 Schema 的字段级说明文档它把配置项分成三组Authentication Configuration认证配置、OIDC Configuration仅 Confidential 客户端显示、Authorizer Configuration授权配置。UI 会根据Client Type动态显隐字段这也是文中多次出现 仅当 Client Type 为 Confidential 时显示 的原因。二、Authentication Configuration认证基础参数以下字段位于认证区块是任何 Auth0 接入都必须理解的基础配置。Provider NameproviderName定义当前 Auth0 SSO 配置实例的人类可读名称示例Auth0 SSO、Company Auth0、Custom Identity Provider作用帮助在日志和用户界面中区分不同的 SSO 配置注意它只是显示名称不影响认证功能本身。Client TypeclientType定义定义应用是公开Public无客户端密钥还是机密Confidential需要客户端密钥可选值Public|Confidential示例Confidential作用决定安全级别与认证流程。Confidential 客户端可以安全存储密钥选择建议SPA 与移动端应用选择Public后端服务与 Web 应用选择ConfidentialAuth0 场景通常使用Confidential。在源码层面clientType直接决定校验分支Auth0Validator.validateAuth0Configuration()根据authConfig.getClientType()进入validateAuth0PublicClient()校验 authority、clientId 与 publicKeyUrls或validateAuth0ConfidentialClient()校验 discoveryUri、JWKS 与客户端凭证两条路径。环境变量对应AUTHENTICATION_CLIENT_TYPE默认public见 openmetadata.yaml。Enable Self SignupselfSignup定义是否允许用户在首次登录时自动创建账户可选值Enabled|Disabled示例Enabled作用控制新用户是自动加入还是需要人工审批注意需要对用户访问做更严格控制时建议Disabled环境变量AUTHENTICATION_ENABLE_SELF_SIGNUP默认true见 openmetadata.yaml。Client IDclientId定义Auth0 中为你的应用分配的 ApplicationClientID示例abc123def456ghi789jkl012mno345pqr作用认证过程中 Auth0 用它识别你的应用获取位置Auth0 控制台 → Applications → 你的应用 → Overview → Application (client) ID。源码中Public 客户端会调用validateClientIdViaAuthorizationEndpoint()向{domain}/authorize构造带client_id、response_typecode的测试 URL 并禁用重定向请求若 Auth0 返回 302/200跳转到登录页则判定 Client ID 有效返回 400/404 则报 Invalid Auth0 client ID见 Auth0Validator.java。环境变量为AUTHENTICATION_CLIENT_ID。Callback URLcallbackUrl定义Auth0 发送认证响应的重定向 URI示例https://yourapp.company.com/callback作用必须与 Auth0 中配置的值完全一致否则认证失败注意必须在 Auth0 → Applications → Authentication → Redirect URIs 中注册生产环境务必使用 HTTPS。在conf/openmetadata.yaml中对应AUTHENTICATION_CALLBACK_URL注释明确要求形如https://yourhost/api/v1/callback见 openmetadata.yaml。此外该文件还提供additionalTrustedRedirectUrisAUTHENTICATION_ADDITIONAL_TRUSTED_REDIRECT_URIS用于浏览器扩展等额外重定向场景示例即为https://extension-id.chromiumapp.org/auth0说明 Auth0 接入在 OpenMetadata 中是被显式支持的重定向场景。Authorityauthority定义为你的 tenant 签发令牌的 Auth0 端点示例https://dev-abc123.us.auth0.com/your-auth0-domain作用告知 OpenMetadata 应向哪个 Auth0 tenant 做认证注意将your-auth0-domain替换为实际的 Auth0 tenant ID多租户应用可以使用common代替 tenant ID。对应环境变量AUTHENTICATION_AUTHORITY默认https://accounts.google.com。在 Public 客户端校验中validateAuth0Domain()会拼接/.well-known/openid-configuration并实际发起 HTTP 请求要求返回 200 且 discovery 文档必须包含issuer、authorization_endpoint、token_endpoint、userinfo_endpoint四个字段且issuer必须以https://开头见 Auth0Validator.java。Public Key URLspublicKey定义Auth0 发布用于令牌验证的公钥的 URL 列表示例[https://dev-abc123.us.auth0.com/common/discovery/v2.0/keys]作用用于验证来自 Auth0 的 JWT 令牌签名注意通常可从 discovery URI 自动发现极少需要手工配置。源码中的validatePublicKeyUrls()补充了更严格的事实至少有一个公钥 URL 必须是 Auth0 的 JWKS 端点{domain}/.well-known/jwks.jsonURL 的 host 必须以.auth0.com结尾或包含.每个 URL 必须可访问HTTP 200且返回 JSON 中含非空keys数组或 URL 含/pem见 Auth0Validator.java。环境变量为AUTHENTICATION_PUBLIC_KEYS。JWT Principal Claimsprincipals⚠️关键警告配置错误的 claims 会把包括管理员在内的所有用户锁在门外定义用于识别用户主体principal的 JWT claims默认值[email, name, sub]推荐作用决定 JWT 中哪个 claim 用来标识用户注意这些 claims必须存在于 Auth0 签发的 JWT 中顺序很重要第一个匹配的 claim 被用于用户识别常见的 Auth0 claimsemail、name、sub、nickname默认值适用于绝大多数 Auth0 配置仅在有个性化 claim 需求时才修改。环境变量AUTHENTICATION_JWT_PRINCIPAL_CLAIMS在仓库中的默认值为[email,preferred_username,sub]见 openmetadata.yaml与文档推荐的[email, name, sub]略有差异——这正是配置时需要注意的以 UI 表单实际填写为准并确保所选 claim 确实出现在 Auth0 令牌中。JWT Principal Claims MappingjwtPrincipalClaimsMapping定义将 JWT claims 映射为 OpenMetadata 用户属性设置后将覆盖jwtPrincipalClaims示例[email:email, username:preferred_username]格式openmetadata字段:jwt_claim校验要求使用该字段时username与email两个映射必须同时存在只允许username和email两个 key其他 key 一律不允许校验失败时错误会显示在该字段上。重要提示对绝大多数 Auth0 配置来说该字段几乎用不到默认的jwtPrincipalClaimsemail、name、sub已经能正确处理用户识别仅在特殊 claim 需求时才配置。对应环境变量AUTHENTICATION_JWT_PRINCIPAL_CLAIMS_MAPPING默认[]见 openmetadata.yaml。JWT Team Claim MappingjwtTeamClaimMapping定义包含团队/部门信息的 Auth0 claim 或属性用于自动分配团队示例department、groups、organization或自定义用户元数据字段作用登录时根据 Auth0 用户资料中的信息将用户自动分配进 OpenMetadata 已存在的团队工作方式从指定 claim 提取值例如设置为department就读取 Auth0 中用户的部门对数组型 claim如groups会处理数组中的全部值将提取的值与 OpenMetadata 中的团队名进行匹配将用户分配到所有匹配的、类型为Group的团队若团队不存在或类型不是 Group仅记录 warning认证流程继续。Auth0 侧配置标准用户资料字段department、organization自定义用户元数据可在 Auth0 → User Management → Users → User Details 配置基于组/角色的团队可使用groups或rolesclaims可通过 Auth0 Rules 或 Actions 添加自定义 claims 到 JWT 中。注意目标团队必须已在 OpenMetadata 中存在只有类型为Group的团队可被自动分配Organization、BusinessUnit类型不行团队名区分大小写必须精确匹配数组型 claims如groups、roles支持多团队分配。三、OIDC Configuration仅 Confidential 客户端可见的参数以下字段仅在Client Type Confidential时显示。OIDC Client IDid定义用于 Auth0 OIDC 认证的应用客户端 ID示例abc123def456ghi789jkl012mno345pqr作用在 OIDC 流程中向 Auth0 标识你的应用注意与 Auth0 应用注册时的 Client ID 相同。OIDC Client SecretclientSecret定义Confidential 客户端与 Auth0 认证时使用的密钥示例abc123def456ghi789jkl012mno345pqr678st作用Confidential 客户端安全认证 Auth0 所必需注意在 Auth0 → Applications → Certificates secrets 生成妥善保管并定期轮换仅 Confidential 客户端类型显示。源码中validateClientCredentials()会先校验 Client ID 是否被 Auth0 识别400/404 报 Invalid client ID再向{domain}/oauth/token以grant_typeclient_credentials提交表单返回 200 即通过响应中invalid_client/unauthorized_client对应无效密钥、access_denied对应访问被拒见 Auth0Validator.java。对应环境变量OIDC_CLIENT_ID与OIDC_CLIENT_SECRET。OIDC Request Scopesscopes定义认证过程中向 Auth0 请求的权限范围默认值openid email profile示例openid email profile User.Read作用决定 OpenMetadata 可以访问哪些用户信息注意多数场景下openid email profile已足够。OIDC Discovery URIdiscoveryUri定义Auth0 的 OpenID Connect 元数据端点示例https://dev-abc123.us.auth0.com/your-auth0-domain/v2.0/.well-known/openid-configuration作用让 OpenMetadata 自动发现 Auth0 的 OIDC 端点注意将your-auth0-domain替换为实际 tenant ID。这是 Confidential 客户端校验的核心输入extractAuth0DomainFromOidcConfig()会从discoveryUri中剔除/.well-known/openid-configuration后缀以还原 Auth0 域名若为空则直接抛出IllegalArgumentException见 Auth0Validator.java。随后OidcDiscoveryValidator.validateAgainstDiscovery()会用该 discovery 文档校验 scopes、response types 等声明是否匹配。对应环境变量OIDC_DISCOVERY_URI。OIDC Use NonceuseNonce定义防止 OIDC 流程中重放攻击的安全特性默认值false作用确保每次认证请求唯一增强安全性注意若提供商支持可开启以获得额外安全保护。OIDC Disable PKCEdisablePkce定义是否禁用 Proof Key for Code ExchangePKCE 安全扩展默认值false作用PKCE 为授权码流程增加安全性注意出于安全考虑应保持启用即false。OIDC Max Clock SkewmaxClockSkew定义验证令牌时系统间允许的最大时间差示例0秒作用避免因轻微时钟偏差导致令牌校验失败注意通常 0 即可除非存在明显的时钟偏差问题。OIDC Client Authentication MethodclientAuthenticationMethod定义客户端与 Auth0 认证时使用的方法默认值client_secret_post自动配置作用OpenMetadata 使用 Auth0 支持的client_secret_post注意该字段隐藏且自动配置Auth0 同时支持client_secret_post与client_secret_basic。OpenMetadata Access Token ValiditytokenValidity定义OpenMetadata 访问 JWT 的有效期秒默认值36001 小时最小值1 秒示例3600作用控制用于 OpenMetadata API 请求的令牌生命周期注意该值不会继承 Auth0 令牌的生命周期。OIDC Custom ParameterscustomParams定义OIDC 请求中附加发送的额外参数示例{prompt: select_account, domain_hint: company.com}作用允许定制 Auth0 的认证行为注意常用参数包括prompt、domain_hint、login_hint。OIDC Callback URL / Redirect URIcallbackUrl定义认证完成后 Auth0 重定向到的 URL自动生成该字段自动填充为{your-domain}/callback示例https://openmetadata.company.com/callback作用必须在 Auth0 配置中注册注意该字段为只读不可编辑请原样复制此 URL 并添加到 Auth0 的允许重定向 URI 列表格式恒为{your-domain}/callback。OIDC Max AgemaxAge定义重新认证前允许的最大认证时长秒示例3600作用控制用户需要重新认证的频率注意留空表示无特定 max age 要求。OIDC Promptprompt定义控制 Auth0 的认证提示行为可选值none|login|consent|select_account示例select_account作用影响认证过程中的用户体验含义login始终要求输入凭证consent提示授予权限select_account显示账户选择器。OIDC Session ExpirysessionExpiry定义用户会话的有效时长秒默认值6048007 天示例604800作用控制用户需要重新认证的频率注意仅适用于 Confidential 客户端。该值与 openmetadata.yaml 中AUTHENTICATION_SESSION_EXPIRY的默认值604800一致注释注明 7 days; applies to all auth providers。四、Authorizer Configuration授权与管理员配置Admin PrincipalsadminPrincipals定义拥有管理员权限的用户主体列表示例[admin, superuser]作用这些用户在 OpenMetadata 中拥有全部管理权限注意使用用户名不是邮箱地址——用户名取自邮箱前缀之前的部分。Principal DomainprincipalDomain定义用户主体的默认域名示例company.com作用仅提供用户名时用于构造完整用户主体注意通常填写组织的首要域名。Enforce Principal DomainenforcePrincipalDomain定义是否强制所有用户属于 principal 域名默认值false示例true作用通过限制只有特定域名用户可访问增加一层安全防护。对应环境变量AUTHORIZER_ENFORCE_PRINCIPAL_DOMAIN默认false见 openmetadata.yaml。Allowed DomainsallowedDomains定义允许访问 OpenMetadata 的邮箱域名列表示例[company.com, partner-company.com]作用精细控制哪些邮箱域名可以通过 Auth0 认证注意与enforcePrincipalDomain配合使用启用enforcePrincipalDomain后只有邮箱地址属于这些域名的用户可访问如果只有一个 Auth0 tenant可留空或只使用单个principalDomain当 Auth0 tenant 包含多个域名的用户时非常有用。对应环境变量AUTHORIZER_ALLOWED_DOMAINS默认[]见 openmetadata.yaml。Enable Secure Socket ConnectionenableSecureSocketConnection定义是否使用 SSL/TLS 建立安全连接默认值false示例true作用确保通信加密保障安全注意生产环境应启用。对应环境变量AUTHORIZER_ENABLE_SECURE_SOCKET默认false见 openmetadata.yaml。五、配置文件与环境变量对照快速落地 Auth0在conf/openmetadata.yaml中认证与授权配置都支持环境变量注入。落地 Auth0 时将provider设为auth0并按需覆盖下列变量完整上下文见 openmetadata.yamlUI 字段环境变量默认值Client TypeAUTHENTICATION_CLIENT_TYPEpublicProviderAUTHENTICATION_PROVIDERbasicAuth0 场景设为auth0Client IDAUTHENTICATION_CLIENT_ID空Callback URLAUTHENTICATION_CALLBACK_URL空形如https://yourhost/api/v1/callbackAuthorityAUTHENTICATION_AUTHORITYhttps://accounts.google.comPublic Key URLsAUTHENTICATION_PUBLIC_KEYS本机 JWKSJWT Principal ClaimsAUTHENTICATION_JWT_PRINCIPAL_CLAIMS[email,preferred_username,sub]JWT Claims MappingAUTHENTICATION_JWT_PRINCIPAL_CLAIMS_MAPPING[]Enable Self SignupAUTHENTICATION_ENABLE_SELF_SIGNUPtrueSession ExpiryAUTHENTICATION_SESSION_EXPIRY604800OIDC Client IDOIDC_CLIENT_ID空OIDC Client SecretOIDC_CLIENT_SECRET空OIDC Discovery URIOIDC_DISCOVERY_URI空Enforce Principal DomainAUTHORIZER_ENFORCE_PRINCIPAL_DOMAINfalseAllowed DomainsAUTHORIZER_ALLOWED_DOMAINS[]Enable Secure SocketAUTHORIZER_ENABLE_SECURE_SOCKETfalse六、底层校验链路与常见失败点理解 Auth0Validator.java 的校验顺序有助于快速定位配置问题Public 客户端校验 authority实际请求/.well-known/openid-configuration→ 校验 Client ID向/authorize发无重定向请求判断 302/400/404→ 校验 Public Key URLs必须包含{domain}/.well-known/jwks.json。Confidential 客户端从discoveryUri提取 Auth0 域名 → 用 discovery 文档交叉校验 → 校验 JWKS 公钥 URL → 调用/oauth/token用client_credentials实测凭证有效性。对应的单元测试 Auth0ValidatorTest.java 覆盖了典型失败场景无效 authority期望报 Domain validation failed、Confidential 客户端缺失 discoveryUri期望报错含 Auth0 domain 或 discoveryUri、空 client secret、非法公钥 URL 域名等可作为排查时的对照清单。常见失败点归纳Callback URL 不一致OpenMetadata 侧自动生成的{your-domain}/callback必须原样登记到 Auth0 Redirect URIs任何出入都会导致回调失败JWT claims 选择不当jwtPrincipalClaims中配置的 claim 若不在 Auth0 令牌中将导致所有用户含管理员无法识别这正是文档中红色警告的来源Discovery URI 域名错误Confidential 客户端无法从discoveryUri提取合法域名时会直接校验失败公钥 URL 不含 Auth0 JWKS 端点至少一个 URL 必须是{domain}/.well-known/jwks.json且域名需匹配.auth0.com模式团队自动分配失效目标团队不存在、团队类型不是 Group、或团队名大小写不匹配均只记录 warning 而不会中断认证。七、总结Auth0 SSO 的接入在 OpenMetadata 中是一条被完整支持的认证路径UI 表单覆盖了认证、OIDC、授权三组参数JSON Schema 定义了clientId、secretKey、domain三个基础属性Auth0Validator则提供了从 discovery 文档到 JWKS、再到实际 token 请求的多层校验。按本文逐项填写并核对 Auth0 侧的 Redirect URI、Client Secret 与 claims 配置即可完成安全可靠的 Auth0 单点登录接入。【免费下载链接】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），仅供参考