ByteHouse云数仓版
ByteHouse云数仓版
- 文档首页
ByteHouse云数仓版用户指南（3.0）Agent 可观测为 Langfuse 配置 OIDC 单点登录
复制全文
下载 pdf
文档反馈
问问助手ByteHouse（云数仓版）提供全托管的 Langfuse 服务。管理员可以通过 OIDC（OpenID Connect，开放身份连接协议）接入企业身份提供方，实现 SSO（Single Sign-On，单点登录）。完成接入后，用户可使用企业统一账号登录 Langfuse UI（User Interface，用户界面）。
本文面向具备 ByteHouse 服务管理权限及企业身份应用配置权限的管理员，介绍 OIDC 应用注册、回调地址配置，以及登录和项目访问验证。服务开通、网络配置及日常管理方法，请参见 Langfuse。
企业身份提供方负责校验用户身份，并按企业策略执行多因素认证或访问控制；Langfuse 作为 OIDC 客户端，发起登录请求、校验认证结果并建立登录会话。用户能够访问哪些组织和项目，仍由 Langfuse 的组织成员关系和角色决定。本文配置的是网页用户登录，应用接入仍使用项目 API Key（应用程序编程接口密钥）。
| 概念 | 说明及与本次配置的关系 |
|---|---|
| SSO（Single Sign-On，单点登录） | 用户在统一身份服务完成认证后，可访问接入该服务的应用；能否免于重复认证取决于身份服务的会话和策略。 |
| OIDC（OpenID Connect，开放身份连接协议） | 应用获取和校验用户认证结果的标准协议，是本次配置使用的登录协议。 |
| IdP（Identity Provider，身份提供方） | 负责认证用户并向应用提供身份信息的服务。可以选用企业自建服务或托管身份服务。 |
| OIDC 客户端及客户端凭据 | 客户端是接入身份服务的应用，本次为 Langfuse。Client ID 标识该应用，Client Secret 用于客户端认证，由 Langfuse 服务端使用。 |
| Issuer（颁发者地址） | 身份提供方的唯一 URL 标识，用于识别并校验认证结果的签发来源。Langfuse 的OIDC 颁发者地址填写此值。 |
| Discovery URL（OIDC 发现文档地址） | 用于获取身份服务元数据，其中包含 issuer、授权端点、令牌端点和签名公钥地址等信息。配置颁发者地址时，复制其中的 issuer 值。 |
| Redirect URI（回调地址） | 身份认证后浏览器返回 Langfuse 的地址，需要在身份提供方的客户端配置中登记为允许的回调地址。 |
- 确认服务和访问条件。 在目标地域及环境下，确认 ByteHouse（云数仓版）托管 Langfuse 已开通且处于运行中。使用公网访问时，完成公网 IP 绑定，并将浏览器所在网络的出口地址段加入白名单，确认能够打开 Langfuse 服务地址。操作方法请参见开通 Langfuse 服务。
- 准备控制台管理账号。 使用新版控制台，并准备已授权 ByteHouseFullAccess 或 ByteHouseAccountAdminAccess 任一策略的 IAM（Identity and Access Management，身份与访问管理）账号，用于变更 Langfuse 登录配置。
- 准备企业身份应用。 确认 IdP 支持 OIDC，并具备创建或维护应用、获取客户端凭据、配置回调地址及用户声明的权限。Keycloak、Okta、Microsoft Entra ID 等为 IdP 示例；具体界面和配置位置以所用提供方为准。
- 准备测试用户。 准备一个已获 IdP 应用访问授权的用户，用于验证登录和项目访问。
回调地址是企业 IdP 完成认证后将浏览器重定向回 Langfuse 的地址，需要在 IdP 应用中登记为允许的 Redirect URI。Langfuse 的托管登录配置页不要求手动填写此项，IdP 侧仍需登记正确地址。
注意
当前 ByteHouse 托管 Langfuse 的回调端口固定为 3000，回调路径固定为 /api/auth/callback/custom。控制台的公网域名不包含端口号；在 IdP 登记回调地址时，需要手动添加 :3000，并保留固定回调路径。
从控制台获取域名并生成回调地址
- 在 ByteHouse（云数仓版）新版控制台确认目标地域和环境，进入 Agent可观测 > Langfuse > 实例信息。在网络设置区域，单击公网域名后的复制图标，复制该域名。
- 在复制的公网域名前加上
https://，在域名后添加固定端口:3000，再拼接/api/auth/callback/custom。不要追加其他路径、查询参数或末尾斜杠。 - 记录生成的完整地址，供下一节注册 OIDC 应用时登记。
| 项目 | 内容 |
|---|---|
| 回调地址格式 | https://<公网域名>:3000/api/auth/callback/custom |
| 公网域名示例 | langfuse.example.com |
| 对应完整回调地址 | https://langfuse.example.com:3000/api/auth/callback/custom |
将示例中的 langfuse.example.com 替换为从控制台复制的公网域名。端口 3000 和回调路径 /api/auth/callback/custom 保持不变。
在企业 IdP 中创建或维护供 Langfuse 使用的 OIDC 应用，并按下表配置。不同提供方的字段名称可能不同，请结合其 OIDC 应用配置说明完成操作。
| 配置项 | 配置说明 |
|---|---|
| 协议 | OpenID Connect（OIDC）。 |
| 授权流程 | Authorization Code Flow（授权码流程）。 |
| Redirect URI | 登记由控制台公网域名、HTTPS 协议、固定端口 3000 和回调路径组成的完整地址。 |
| 授权范围（scope） | openid email profile，使用空格分隔。scope 表示应用请求的授权范围：openid 用于请求 OIDC 身份认证，email 用于请求邮箱信息，profile 用于请求姓名、头像等基本资料。 |
| 客户端凭据 | 取得此应用的 Client ID 和 Client Secret，供后续托管控制台配置使用。 |
| 签名算法 | 使用 RS256。 |
确认 OIDC 颁发者地址
OIDC 颁发者地址（Issuer URL）标识企业 IdP 的 OIDC 发行方。在 IdP 的应用配置页或 Discovery 文档中取得 issuer 的准确值。例如：
https://id.example.com/realms/acme
Langfuse 通过 Discovery 文档获取授权、令牌及验签公钥等端点信息。IdP 的 Discovery 文档应可通过公网 HTTPS 访问。上述 Issuer 示例对应的 Discovery 地址为：
https://id.example.com/realms/acme/.well-known/openid-configuration
控制台填写 issuer 值本身，不填写 Discovery 文档完整地址、IdP 登录页或授权端点，也不填写 Langfuse 服务地址。若 Issuer 本身带末尾斜杠，构造 Discovery 地址时避免重复斜杠；控制台中的 Issuer 仍应保留 IdP 发布的准确值。
网络检查需要区分访问方：浏览器需要访问 IdP 授权页面和 Langfuse 回调地址；托管 Langfuse 服务需要访问 Discovery、Token（令牌）端点和验签公钥端点，使用 UserInfo（用户信息）接口时还需访问该端点。电脑能够打开 Discovery，并不代表托管服务已能访问所有端点。如 IdP 要求按来源地址放行，请联系 ByteHouse 团队确认所需配置。
配置用户声明
声明（claim）是 IdP 实际返回的用户信息字段，例如 sub、email 和 name。
请为 Langfuse 应用配置以下标准声明。自定义姓名或邮箱字段应映射到相应标准声明。
| 声明 | 接入要求 | 用途 |
|---|---|---|
sub | 必需 | 用户在该 IdP 中稳定、唯一的主体标识。 |
email | 必需 | Langfuse 用户的邮箱。 |
name | 建议提供 | 用于在 Langfuse 中展示用户姓名或显示名。 |
picture | 可选 | 用户头像地址。 |
完成身份提供方配置后，请参见配置 SSO 登录，在 ByteHouse 控制台填写客户端 ID、客户端密钥和 OIDC 颁发者地址，启用 SSO。配置变更需重启 Langfuse 服务才能生效。 不同登录方式对既有用户的影响，请参见变更登录方式。
- 使用未登录窗口打开 Langfuse 服务地址，从企业 OIDC 登录入口发起认证。
- 确认浏览器跳转到预期的企业 IdP 登录页面。
- 使用已获 IdP 应用访问授权的测试用户完成认证。能够按正常 SSO 流程返回并进入 Langfuse UI，即表示 SSO 登录验证通过。随后核对用户邮箱和显示名；显示名为空时，参见“设置 SSO 用户的显示名”。
- 确认测试用户已加入目标 Langfuse 组织并分配适当角色。若用户已注册但尚未加入组织，由管理员在 ByteHouse 控制台的组织管理 > 成员管理 > 添加成员中选择用户、分配角色并确认。若用户列表中未出现该账号，请联系 ByteHouse 团队确认用户注册状态。具体操作请参见添加或移除组织成员。
- 返回 Langfuse UI，确认能够看到目标组织、进入目标项目，并按所分配角色访问相应功能。同一组织下的全部项目继承该组织角色。
首次通过 SSO 登录时，IdP 可能要求用户确认授权。例如，Agent Identity 会显示如下授权访问页面，列出 openid、email 和 profile 等授权范围。确认应用及授权信息后，单击允许访问继续登录。具体界面以所用 IdP 为准。
说明
IdP 应用授权决定是否允许完成企业身份认证，Langfuse 组织角色决定能访问哪些项目、执行哪些操作。认证成功后没有项目访问权限，应检查成员关系和角色。
设置 SSO 用户的显示名
SSO 用户的显示名可以由 IdP 的标准 name 属性提供，具体配置方法以所用 IdP 为准。如果 IdP 未提供 name，登录后显示名或 ByteHouse 控制台中的用户名可能为空或显示为“-”；这本身不表示 SSO 登录失败。用户也可以在 Langfuse 中手动设置显示名。
例如，下图中的 SSO 用户在 ByteHouse 控制台中的用户名显示为“-”。
- 在 Langfuse UI 中，单击左下角的用户菜单，选择 Account Settings（账号设置）。
- 在 General（常规） 页面的 Display Name（显示名） 区域，输入希望显示的用户名，单击 Save（保存）。
- 返回 ByteHouse 控制台的用户及登录管理页，刷新用户列表，并核对该用户的用户名是否已显示。
IdP 提示回调地址不匹配
检查 IdP 应用登记的 Redirect URI 是否按控制台公网域名生成，并包含 https://、固定端口 :3000 和路径 /api/auth/callback/custom，以及是否多了末尾斜杠或参数。
例如，回调地址应按以下格式登记：
https://langfuse.example.com:3000/api/auth/callback/custom
如果登记为 https://langfuse.example.com/api/auth/callback/custom，会遗漏固定端口 3000。补上 :3000，保存 IdP 应用配置后，从 Langfuse 重新发起登录。控制台展示的公网域名不包含端口，登记时仍需手动添加。
无法发现 OIDC 配置或访问端点
检查控制台填写的是否为准确 Issuer，并确认对应 Discovery 地址返回有效 OIDC JSON。检查其中的 issuer 与配置一致，以及授权、Token 和验签公钥地址是否可由各自访问方连通；按需检查 UserInfo。需要来源放行时，联系 ByteHouse 团队确认托管服务的访问来源。
IdP 已认证，但 Langfuse 登录失败或用户信息不完整
先核对 Client ID 和 Client Secret 是否属于同一 IdP 应用，再检查 IdP 应用的客户端认证配置。确认应用已配置 openid email profile scope，以及 sub、email 和按需提供的 name 标准声明；自定义声明应映射到标准字段。
name 为建议字段，其缺失不代表必然登录失败。SSO 登录成功后，若仅是显示名为空或 ByteHouse 控制台中的用户名显示为“-”，可按“设置 SSO 用户的显示名”处理。
登录成功，但看不到组织或无法进入项目
在 ByteHouse 控制台的用户及登录管理页确认用户已注册，再检查目标组织是否包含该用户及其角色。若用户列表中未出现该账号，请联系 ByteHouse 团队确认用户注册状态。管理员按添加或移除组织成员维护成员关系；组织内全部项目继承该组织角色，不单独配置项目成员角色。
保存后仍不能使用 SSO，或旧入口显示 NextAuth.js 错误
确认当前实例的 SSO 已启用，并且配置保存后已完成重启。重新打开 Langfuse，使用当前登录入口。关闭 SSO 后继续使用旧入口，认证返回时可能出现：
Error: This action with HTTP GET is not supported by NextAuth.js
若当前仅开启邮箱登录，使用可用的邮箱账号登录；需要 SSO 时，重新启用、保存并确认重启后再验证。完整处理方法请参见 SSO 登录失败并显示 NextAuth.js 错误。问题持续时，保留实例或环境标识、发生时间及错误消息，去除密钥和令牌等敏感内容后联系技术支持。