文档 / SCIM 与组织密钥作用域的 API 路由

SCIM 与组织密钥作用域的 API 路由

SCIM 与组织 API 在 Enterprise 计划和自托管企业版中可用;Hobby、Core、Pro 计划不可用。

通过组织作用域的 API 密钥,你可以管理项目、用户和项目/组织成员资格(参见 RBAC 文档)。

Langfuse 是开放的,旨在通过自定义工作流和集成进行扩展。你可以使用这些端点在你的 Langfuse 组织上自动化项目和用户管理。

本文档涵盖组织管理 API、符合 SCIM 的用户配置端点,并包含一份在 Langfuse 中设置 Okta 身份验证和用户配置的综合指南。

如果你自托管 Langfuse,可以使用 Instance Management API 跨实例管理组织。

身份验证

使用 Basic Auth 对 API 进行身份验证。组织作用域的 API 密钥可以通过 Instance Management API 或在 Langfuse UI 的 Organization Settings 中创建。

示例:

bash

curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects/{projectId}/apiKeys

组织管理

所有适用的端点都标有 (requires organization-scoped API key)。这些包括以下路由:

POST /api/public/projects
PUT /api/public/projects/
DELETE /api/public/projects/
GET /api/public/projects//apiKeys
POST /api/public/projects//apiKeys
DELETE /api/public/projects//apiKeys/
PUT /api/public/organizations/memberships
GET /api/public/organizations/memberships
PUT /api/public/projects//memberships
DELETE /api/public/projects//memberships

更多细节参见 API Reference。

通过 SCIM 进行用户管理

此外,我们实现了以下符合 SCIM 的端点。对它们使用 /api/public/scim 作为基础 URI。

要在 Langfuse 中创建新用户,你可以使用 SCIM 风格的端点和 POST /Users。如果电子邮件尚不存在,这将创建一个新用户。然后它会将用户添加到角色为 NONE 的组织(除非提供了 roles 属性,参见下面的 Okta 指南)。

之后,可以使用成员资格端点在组织或项目级别更新角色(见上文)。

当 SCIM 取消配置并重新配置用户时(例如在初始 SCIM 设置或 IdP 同步期间),用户的组织角色可能会被 SCIM roles 属性中配置的角色覆盖(默认为 NONE)。为避免意外的角色降级,请确保在启用 SCIM 配置之前,将 IdP 中的 roles 属性设置为正确的值——例如组织所有者设为 OWNER。

要从组织中移除用户,请调用 DELETE /Users/ 端点。这不会删除用户本身,只会删除其与组织的成员资格。

你可以通过 API 为用户提供初始密码并与他们共享,或使用单点登录(SSO)对用户进行身份验证。在后一种情况下,你需要:

Langfuse Cloud:配置企业 SSO 提供商(文档)。
自托管:为你的 SSO 提供商配置 AUTH__ALLOW_ACCOUNT_LINKING,以确保用户账户正确关联 SSO 文档。

以下 SCIM 端点可用:

GET /ServiceProviderConfig
GET /ResourceTypes
GET /Schemas
GET /Users
POST /Users
GET /Users/
DELETE /Users/

SCIM 厂商指南

Okta

本指南将介绍如何为 Langfuse 设置 Okta 用户配置。首先,你需要设置通过 OIDC 的身份验证。

对于用户配置,Langfuse 支持 SCIM 2.0 协议。要在 Okta 中设置用户配置,请遵循以下步骤:

创建 SAML/SCIM 应用:
- 登录你的 Okta 管理控制台。
- 导航到 Applications > Create App Integration。
- 选择 SAML 2.0 作为登录方法并点击 Next。
- 填写应用设置。使用你的自托管域或 Langfuse Cloud 域之一。
  - App name:Langfuse SCIM
  - Single sign-on URL:https://your-langfuse-domain.com(langfuse 使用 OIDC 进行身份验证,见上文,这不会被使用)
  - Audience URI:langfuse
- 点击 Next,然后点击 Finish。
配置 SCIM 设置:
- 在 General 标签页,将 Provisioning 设置为 SCIM。
- 在 Provisioning 标签页,编辑你的 SCIM Connection。
- 输入你的凭证:
  - SCIM connector base URL:https://your-langfuse-domain.com/api/public/scim
  - Unique identifier field for users:userName
  - Supported provisioning actions:Import new Users and Profile Updates、Push New Users、Push Profile Updates
  - Basic Auth - Username:使用你 Organization settings 中的公钥。
  - Basic Auth - Password:使用你 Organization settings 中的私钥。
- 测试 API 凭证并按 Save。
配置配置(Provisioning):
- 在 Provisioning 标签页,启用以下选项:
  - Create Users
  - Update User Attributes
  - Deactivate Users
- 点击 Save。
添加默认用户权限(可选):
- 在 Provisioning 标签页,转到 Profile Editor 并添加一个新的 roles 属性:
  - Data type:string array
  - Display Name:Langfuse Roles
  - Variable Name:roles
  - External Name:roles
  - External Namespace:urn:ietf:params:scim:schemas:core:2.0:User
  - Attribute members:NONE、VIEWER、MEMBER、ADMIN、OWNER
  - Attribute type:Personal
- 在 Provisioning 标签页,修改 roles 属性以为新用户设置默认权限。
- 你可以为应用的所有用户设置它以提供默认值。将其设置为 "NONE"、"VIEWER"、"MEMBER"、"ADMIN" 或 "OWNER"。
分配用户:
- 导航到 Assignments 标签页。
- 点击 Assign > Assign to People。
- 选择你要分配给 Langfuse SCIM 应用的用户。你可以在此处覆盖角色。
- 点击 Done,然后点击 Save。
- 用户应在你的 Langfuse Organization 中显示为 Member。

故障排查

用户以 NONE/VIEWER 权限而非其预期的 role 被配置:如果 roles 属性的属性类型为 Group 而非 Personal,通常会发生这种情况。
启用 SCIM 后用户丢失了角色:在初始 SCIM 设置期间,如果用户被取消配置并重新配置,其组织角色会被 SCIM roles 属性中的值覆盖。如果 IdP 中未配置角色,默认为 NONE。要修复此问题,请确保在配置之前在 IdP 配置文件中设置正确的角色(包括组织所有者的 OWNER)。