BytesRouter

主题

LangSmith 文档版本 跟随上游 源快照 100463cd 更新于 2026-10-18

用户管理

本页讲述 LangSmith 中的用户管理功能，包括访问控制、身份验证和自动化用户预配：

设置访问控制

NOTE

RBAC（基于角色的访问控制）是仅对企业客户可用的功能。如果你对此功能感兴趣，请联系我们的销售团队。其他方案默认对所有用户使用 Admin 角色。

TIP

在设置访问控制之前，阅读管理概览页可能会有帮助。

LangSmith 依赖 RBAC 来管理一个工作区内的用户权限。这让你能控制谁能访问你的 LangSmith 工作区以及他们在其中能做什么。带 workspaces:manage 权限的用户能管理工作区设置，带 workspaces:manage-members 权限的用户能添加、移除和更新工作区成员。内置的 Workspace Admin 角色包含这两个权限。

工作区角色及其权限的完整参考，参阅基于角色的访问控制指南。关于每个角色能执行的每个具体操作，参阅组织与工作区操作参考。

创建一个角色

默认情况下，LangSmith 带一组系统角色：

  • Admin：对工作区内所有资源有完全访问。
  • Viewer：对工作区内所有资源有只读访问。
  • Editor：有除工作区管理（添加/移除用户、更改角色、配置服务密钥）之外的完全权限。

如果这些不适合你的访问模型，Organization Admins 能创建自定义角色以满足你的需要。

要创建一个角色，导航到 Organization settings 页中 Members and roles 部分的 Roles 标签。注意你创建的新角色将在你组织内的所有工作区可用。

点击 Create Role 按钮创建一个新角色。会打开一个 Create role 表单。

Create Role

为你想控制访问的各个 LangSmith 资源指派权限。

把一个角色指派给用户

角色设置好之后，你能把它们指派给用户。要把一个角色指派给用户，导航到 Organization settings 页中 Workspaces 部分的 Workspace members 标签

每个用户都会有一个 Role 下拉菜单，你能用它把角色指派给他们。

Assign Role

你也能以一个给定角色邀请新用户。

Invite User

为你的组织设置 SAML SSO

单点登录（SSO）功能**对企业云（Enterprise Cloud）**客户可用，让他们能通过单一身份验证源访问 LangSmith。这让管理员能集中管理团队访问并让信息更安全。

LangSmith 的 SSO 配置用 SAML（Security Assertion Markup Language）2.0 标准构建。SAML 2.0 能把一个身份提供商（IdP）连到你的组织，以获得更容易、更安全的登录体验。

SSO 服务允许用户用一整套凭据（例如一个名字或邮箱地址和密码）访问多个应用。该服务对用户被授予权限的所有应用只身份验证终端用户一次，并消除用户在同一个会话中切换应用时的进一步提示。SSO 的好处包括：

  • 为组织所有者精简跨系统的用户管理。
  • 让组织能强制执行它们自己的安全策略（例如 MFA）。
  • 免去终端用户记住和管理多个密码的需要。通过允许多个应用在一个单一访问点登录，简化终端用户体验。

即时（JIT）预配

LangSmith 在使用 SAML SSO 时支持即时预配。这让一个通过 SAML SSO 登录的人能作为成员自动加入该组织和选定的工作区。关于管理 JIT 预配和用户邀请的详细信息，参阅管理 SSO 组织中的用户访问。

NOTE

JIT 预配只对新用户运行，即那些尚未通过一个不同登录方法以同一邮箱地址拥有该组织访问权的用户。

登录方法与访问

一旦你完成为你的组织的 SAML SSO 配置，用户将能通过 SAML SSO 登录，此外还有其他登录方法，如用户名/密码或 Google 身份验证：

  • 通过 SAML SSO 登录时，用户只能访问配置了 SAML SSO 的对应组织。
  • 以 SAML SSO 为唯一登录方法的用户没有个人组织。
  • 通过任何其他方法登录时，用户能访问配置了 SAML SSO 的组织，以及他们所属的任何其他组织。

强制执行仅 SAML SSO

NOTE

在强制执行仅 SAML SSO 的组织中不支持用户邀请。初始工作区成员资格和角色由 JIT 预配决定，之后的更改能在 UI 中管理。 要更多自动化用户管理的灵活性，LangSmith 支持 SCIM。

要确保用户只能在用 SAML SSO 登录、且不用其他方法时访问该组织，勾选 Allow Invites 复选框。这之后，通过非 SSO 登录方法登录、访问该组织的用户被要求用 SAML SSO 重新登录。取消勾选该复选框就能把此设置切回允许所有登录方法。

NOTE

你必须通过 SAML SSO 登录才能把这个设置更新为 Only SAML SSO。这是为了确保 SAML 设置有效，避免把用户锁在你的组织之外。

关于故障排除，参阅 SAML SSO 常见问题。如果设置 SAML SSO 时遇到问题，通过 support.langchain.com 联系 LangChain 支持团队。

前提条件

NOTE

SAML SSO 对处于 Enterprise 方案的组织可用。联系我们的销售团队以了解更多。

  • 你的组织必须在 Enterprise 方案上。
  • 你的身份提供商（IdP）必须支持 SAML 2.0 标准。
  • 只有 Organization Admins 能配置 SAML SSO。

关于连同 SAML 一起用 SCIM 做用户预配和去配的说明确，参阅 SCIM 设置。

初始配置

NOTE

关于 IdP 专属的配置步骤，参阅以下之一：

  1. 在你的 IdP 中：配置一个带以下详情的 SAML 应用，然后复制元数据 URL 或 XML 供步骤 3 使用。

NOTE

以下 URL 取决于你的组织在 GCP US、GCP EU、GCP APAC 还是 AWS US 云区域。确保你选对链接。

  1. Single sign-on URL（或 ACS URL）：

    Region Host / URL
    GCP US {`$ / https://${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
    GCP EU {`$ / https://eu.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
    GCP APAC {`$ / https://apac.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
    AWS US {`$ / https://aws.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}

  2. Audience URI（或 SP Entity ID）：

    Region Host / URL
    GCP US {`$ / https://${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
    GCP EU {`$ / https://eu.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
    GCP APAC {`$ / https://apac.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}
    AWS US {`$ / https://aws.${prefix_1 || "api.smith"}.langchain.com${suffix_1 || ""}`}

  3. Name ID 格式：email address。

  4. Application username：email address。

  5. 必需声明：sub 和 email。

  6. 在 LangSmith 中：前往 Settings -> Members and roles -> SSO Configuration。填入所需信息并提交以激活 SSO 登录：

    1. 填入 SAML metadata URL 或 SAML metadata XML 之一。

    2. 选择 Default workspace role 和 Default workspaces。通过 SSO 登录的新用户会以所选角色被添加到指定的工作区。

      • Default workspace role 和 Default workspaces 可编辑。更新后的设置只适用于新用户，不适用于现有用户。
      • （即将推出）SAML metadata URL 和 SAML metadata XML 可编辑。这通常仅在加密密钥轮换/过期、或元数据 URL 变了但仍用同一 IdP 时才需要。

SAML 属性映射

NOTE

SAML 属性映射是一个仅云功能。自托管部署直接与 IdP 配置 SAML/OIDC 属性——见用 OAuth2.0 和 OIDC 设置 SSO。

LangSmith 云会把一小组标准 SAML 属性（如 email 和 sub）自动传上用户的 JWT。你的 IdP 发出的任何额外、非标准 SAML 属性（例如为 SSO Groups Sync 的 groups）必须先显式列在 SAML 属性映射表中，LangSmith 才能读它。

属性流（1:1）：

  1. IdP：发出一个带配置名的 SAML 属性（例如 groups）。
  2. SAML 属性映射：只有当属性名出现在 SSO 提供商的 SAML Attribute Mapping 表中时，才把该属性传上用户的 JWT。标准属性自动转发；非标准属性除非显式列出否则被丢弃。
  3. LangSmith：按名读 JWT 声明（例如 SSO Groups Sync 的 Groups claim field 的值）。

属性名端到端保留：IdP 属性名、SAML 属性映射条目，以及下游的 LangSmith 设置都用同一个字符串。

配置

在 Settings > Members and roles > SSO Configuration 中，滚到 SAML Attribute Mapping 节，并为你想转发的每个非标准属性添加一行：

列描述
Attribute name你的 IdP 发出的 SAML 属性名。必须匹配 LangSmith 下游期望的 JWT 声明名（对 SSO Groups Sync，它匹配 Groups claim field 值）。
Array若该属性是多值的（一个字符串列表）则勾选它。标量（单值）属性保持不勾选。例子：对 groups 勾选它；对 full_name 保持不勾选。

对每个额外属性点击 Add row，然后 Save。空的映射表意味着没有非标准属性流向 JWT。

Entra ID（Azure）

更多信息，见 Microsoft 的文档。

步骤 1：创建一个新的 Entra ID 应用集成

  1. 用一个特权角色（例如 Global Administrator）登录 Azure 门户。在左侧导航窗格，选择 Entra ID 服务。

  2. 导航到 Enterprise Applications，然后选择 All Applications。

  3. 点击 Create your own application。

  4. 在 Create your own application 窗口中：

    1. 为你的应用输入一个名字（例如 LangSmith）。
    2. 选择 Integrate any other application you don't find in the gallery (Non-gallery)。

  5. 点击 Create。

步骤 2：配置 Entra ID 应用并获取 SAML 元数据

  1. 打开你创建的那个企业应用。

  2. 在左侧导航，选择 Manage > Single sign-on。

  3. 在 Single sign-on 页面，点击 SAML。

  4. 更新 Basic SAML Configuration：

    1. Identifier (Entity ID)：

      Region Host / URL
      GCP US {`$ / https://${prefix_2 || "api.smith"}.langchain.com${suffix_2 || ""}`}
      GCP EU {`$ / https://eu.${prefix_2 || "api.smith"}.langchain.com${suffix_2 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_2 || "api.smith"}.langchain.com${suffix_2 || ""}`}
      AWS US {`$ / https://aws.${prefix_2 || "api.smith"}.langchain.com${suffix_2 || ""}`}

    2. Reply URL (Assertion Consumer Service URL)：

      Region Host / URL
      GCP US {`$ / https://${prefix_3 || "api.smith"}.langchain.com${suffix_3 || ""}`}
      GCP EU {`$ / https://eu.${prefix_3 || "api.smith"}.langchain.com${suffix_3 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_3 || "api.smith"}.langchain.com${suffix_3 || ""}`}
      AWS US {`$ / https://aws.${prefix_3 || "api.smith"}.langchain.com${suffix_3 || ""}`}

    3. 把 Relay State、Logout Url 和 Sign on URL 留空。

    4. 点击 Save。

  5. 确保必需声明带 Namespace 存在：http://schemas.xmlsoap.org/ws/2005/05/identity/claims：

    1. sub：user.objectid。
    2. emailaddress：user.userprincipalname 或 user.mail（若用后者，确保所有用户在 Contact Information 下填了 Email 字段）。
    3. （可选）对于 SCIM，关于 Unique User Identifier (Name ID) 的具体说明见设置文档。

  6. 在 SAML-based Sign-on 页面，SAML Certificates 下，复制 App Federation Metadata URL。

步骤 3：设置 LangSmith SSO 配置

遵循初始配置下 Fill in required information 步骤中的说明，用前一步的元数据 URL。

步骤 4：验证 SSO 设置

  1. 在 Entra ID 中把该应用指派给用户/群组：

    1. 选择 Manage > Users and groups。

    2. 点击 Add user/group。

    3. 在 Add Assignment 窗口中：

      1. 在 Users 下，点击 None Selected。
      2. 搜索你想指派给企业应用的用户，然后点击 Select。
      3. 核实用户已被选中，并点击 Assign。

  2. 让用户通过 SSO Configuration 页面的唯一登录 URL 登录，或前往 Manage > Single sign-on 并选择 Test single sign-on with (application name)。

Google

更多信息，见 Google 的文档。

步骤 1：创建并配置 Google Workspace SAML 应用

  1. 确保你登录的是一个带适当权限的管理员账户。

  2. 在 Admin console 中，前往 Menu -> Apps -> Web and mobile apps。

  3. 点击 Add App，然后 Add custom SAML app。

  4. 输入应用名，并可选地上传一个图标。点击 Continue。

  5. 在 Google Identity Provider details 页面，下载 IDP metadata 并保存以供步骤 2 使用。点击 Continue。

  6. 在 Service Provider Details 窗口中，输入：

    1. ACS URL：

      Region Host / URL
      GCP US {`$ / https://${prefix_4 || "api.smith"}.langchain.com${suffix_4 || ""}`}
      GCP EU {`$ / https://eu.${prefix_4 || "api.smith"}.langchain.com${suffix_4 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_4 || "api.smith"}.langchain.com${suffix_4 || ""}`}
      AWS US {`$ / https://aws.${prefix_4 || "api.smith"}.langchain.com${suffix_4 || ""}`}

    2. Entity ID：

      Region Host / URL
      GCP US {`$ / https://${prefix_5 || "api.smith"}.langchain.com${suffix_5 || ""}`}
      GCP EU {`$ / https://eu.${prefix_5 || "api.smith"}.langchain.com${suffix_5 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_5 || "api.smith"}.langchain.com${suffix_5 || ""}`}
      AWS US {`$ / https://aws.${prefix_5 || "api.smith"}.langchain.com${suffix_5 || ""}`}

    3. 把 Start URL 和 Signed response 框留空。

    4. 把 Name ID 格式设为 EMAIL，并把 Name ID 留为默认（Basic Information > Primary email）。

    5. 点击 Continue。

  7. 用 Add mapping 确保必需声明存在：

    1. Basic Information > Primary email -> email

步骤 2：设置 LangSmith SSO 配置

遵循初始配置下 Fill in required information 步骤中的说明，用前一步的 IDP metadata 作为元数据 XML。

步骤 3：在 Google 中开启 SAML 应用

  1. 在 Menu -> Apps -> Web and mobile apps 下选择该 SAML 应用

  2. 点击 User access。

  3. 开启该服务：

    1. 要为你组织中的每个人开启该服务，点击 On for everyone，然后点击 Save。

    2. 要为一个组织单元开启该服务：

      1. 在左侧，选择该组织单元然后 On。
      2. 若 Service status 设为 Inherited，且你想在父级设置改变时仍保留更新后的设置，点击 Override。
      3. 若 Service status 设为 Overridden，要么点击 Inherit 回退到与其父级相同的设置，要么点击 Save 在父级设置改变时仍保留新设置。

    3. 要为跨或在一个组织单元内的一组用户开启一个服务，选择一个访问组。详情见使用组来自定义服务访问。

  4. 确保你用户用来登录 LangSmith 的邮箱地址，与他们用来登录你 Google 域的邮箱地址一致。

步骤 4：验证 SSO 设置

让一个有访问权的用户通过 SSO Configuration 页面的唯一登录 URL 登录，或前往 Google 中的 SAML 应用页面并点击 TEST SAML LOGIN。

Okta

受支持的功能

  • IdP 发起的 SSO（单点登录）
  • SP 发起的 SSO
  • 即时预配
  • 强制执行仅 SSO

配置步骤

更多信息，见 Okta 的文档。

步骤 1：创建并配置 Okta SAML 应用

经由 Okta 集成网络（推荐）

  1. 登录 Okta。

  2. 在右上角，选择 Admin。该按钮在 Admin 区域不可见。

  3. 选择 Browse App Integration Catalog。

  4. 找到并选择 LangSmith 应用。

  5. 在应用概览页面，选择 Add Integration。

  6. 把 ApiUrlBase 留空。

  7. 填入 AuthHost：

    Region Host / URL
    GCP US {`$ / https://${prefix_6 || "api.smith"}.langchain.com${suffix_6 || ""}`}
    GCP EU {`$ / https://eu.${prefix_6 || "api.smith"}.langchain.com${suffix_6 || ""}`}
    GCP APAC {`$ / https://apac.${prefix_6 || "api.smith"}.langchain.com${suffix_6 || ""}`}
    AWS US {`$ / https://aws.${prefix_6 || "api.smith"}.langchain.com${suffix_6 || ""}`}

  8. （可选，若计划同时使用 SCIM）填入 LangSmithUrl：

    Region Host / URL
    GCP US {`$ / https://${prefix_7 || "api.smith"}.langchain.com${suffix_7 || ""}`}
    GCP EU {`$ / https://eu.${prefix_7 || "api.smith"}.langchain.com${suffix_7 || ""}`}
    GCP APAC {`$ / https://apac.${prefix_7 || "api.smith"}.langchain.com${suffix_7 || ""}`}
    AWS US {`$ / https://aws.${prefix_7 || "api.smith"}.langchain.com${suffix_7 || ""}`}

  9. 在 Application Visibility 下，保持该框未勾选。

  10. 选择 Next。

  11. 选择 SAML 2.0。

  12. 填入 Sign-On Options：

    • Application username format：Email
    • Update application username on：Create and update

  13. 从 Sign On Options 页面复制 Metadata URL 供下一步使用。

Via Custom App Integration

NOTE

SCIM 能用一个自定义应用集成工作，尽管推荐 Okta Integration Network 应用。关于 SCIM 设置，见用自定义 SAML 应用配置 SCIM。

  1. 以管理员登录 Okta，并前往 Okta Admin console。

  2. 在 Applications > Applications 下点击 Create App Integration。

  3. 选择 SAML 2.0。

  4. 输入一个 App name（例如 LangSmith），并可选一个 App logo，然后点击 Next。

  5. 在 Configure SAML 页面输入以下信息：

    1. Single sign-on URL（ACS URL）。保持 Use this for Recipient URL and Destination URL 勾选：

      Region Host / URL
      GCP US {`$ / https://${prefix_8 || "api.smith"}.langchain.com${suffix_8 || ""}`}
      GCP EU {`$ / https://eu.${prefix_8 || "api.smith"}.langchain.com${suffix_8 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_8 || "api.smith"}.langchain.com${suffix_8 || ""}`}
      AWS US {`$ / https://aws.${prefix_8 || "api.smith"}.langchain.com${suffix_8 || ""}`}

    2. Audience URI (SP Entity ID)：

      Region Host / URL
      GCP US {`$ / https://${prefix_9 || "api.smith"}.langchain.com${suffix_9 || ""}`}
      GCP EU {`$ / https://eu.${prefix_9 || "api.smith"}.langchain.com${suffix_9 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_9 || "api.smith"}.langchain.com${suffix_9 || ""}`}
      AWS US {`$ / https://aws.${prefix_9 || "api.smith"}.langchain.com${suffix_9 || ""}`}

    3. Name ID format：Persistent。

    4. Application username：email。

    5. 把其余字段留空或设为其默认。

    6. 点击 Next。

  6. 点击 Finish。

  7. 从 Sign On 页面复制 Metadata URL 供下一步使用。

步骤 2：设置 LangSmith SSO 配置

遵循初始配置下 Fill in required information 步骤中的说明，用前一步的元数据 URL。

步骤 3：在 Okta 中把用户指派给 LangSmith

  1. 在 Applications > Applications 下，选择步骤 1 中创建的 SAML 应用。
  2. 在 Assignments 标签下，点击 Assign，然后 Assign to People 或 Assign to Groups。
  3. 做所需的选择，然后 Assign 和 Done。

步骤 4：验证 SSO 设置

让一个有访问权的用户通过 SSO Configuration 页面的唯一登录 URL 登录，或让一个用户从他们的 Okta 仪表盘选择该应用。

SP 发起的 SSO

一旦配置好服务提供方发起的 SSO，用户就能用一个唯一登录 URL 登录。你能在 LangSmith UI 的 Organization members and roles 然后 SSO configuration 下找到它。

要在登录后把一个用户送到一个特定页面，给登录 URL 添加一个 URL 编码的 redirect_to 路径：

text
https://smith.langchain.com/sso/login/<slug>?redirect_to=%2Fo%2F<organization-id>%2Fprojects%2Fp%2F<project-id>%2Fr%2F<run-id>

该值必须解码为同一主机上一个以 / 开头的路径。在上面的例子中它解码为 /o/<organization-id>/projects/p/<project-id>/r/<run-id>，所以用户会落到那个运行上。指向另一主机的值会被拒绝，用户改落到 LangSmith 首页。

对该路径做编码。一个含其自身查询字符串或片段的未编码路径，会在第一个 & 或 # 处被截断，这会把用户送到一个不完整的目的地。

NOTE

大多数链接不需要这个参数。直接打开一个 LangSmith URL，然后用工作邮箱通过 SSO 登录，已经会把用户带回那个页面。当链接必须自己启动 SAML 登录时（例如一个由脚本生成的、或为通过单一身份提供商登录的团队发布的链接），用 redirect_to。

为你的组织设置 SCIM

NOTE

在找一个比 SCIM 更轻量、无需 IdP 管理员介入就能推送群组的替代方案？见下面的 SSO Groups Sync——它在登录时直接从 SSO 令牌读群组成员资格，并复用同一命名约定。

跨域身份管理系统（SCIM）是一个允许自动化用户预配的开放标准。用 SCIM，你能自动预配和去配你 LangSmith 组织和工作区中的用户，让-user 访问与你组织的身份提供商保持同步。

NOTE

SCIM 对处于 Enterprise 方案的组织可用。联系我们的销售团队以了解更多。

SCIM 在 Helm chart 版本 0.10.41（应用版本 0.10.108）及之后可用。

SCIM 支持仅限 API（见下方说明）。

SCIM 消除了手动用户管理的需要，并确保用户访问始终与你组织的身份系统保持最新。这带来：

  • 自动化用户管理：依据用户在 IdP 中的状态，用户被自动从 LangSmith 添加、更新和移除。
  • 降低管理开销：无需跨多个系统手动管理用户访问。
  • 改进的安全：离开你组织的用户会被自动从 LangSmith 去配。
  • 一致的访问控制：用户属性和群组成员资格在各系统间同步。
  • 扩展团队访问控制：高效管理带许多工作区和自定义角色的大团队。
  • 角色指派：为用户群组选择特定的组织角色和工作区角色。

要求

前置条件

  • 你的组织必须在 Enterprise 方案上。
  • 你的身份提供商（IdP）必须支持 SCIM 2.0。
  • 只有 Organization Admins 能配置 SCIM。
  • 对于云客户：SAML SSO 必须能为你的组织配置。
  • 对于自托管客户：带 Client Secret 的 OAuth 身份验证模式必须启用。
  • 对于自托管客户，必须允许从身份提供商到 LangSmith 的网络流量：
    • Microsoft Entra ID 支持允许列表 IP 范围或一个基于代理的方案来提供连通性。 （详情）。
    • Okta 支持允许列表 IP 或域名（详情） 或一个基于代理的方案（详情）来提供连通性。

NOTE

SCIM 连接通常需要 HTTP/1.1 或更高。如果你的客户端用 HTTP/1.0，你可能会遇到一个 426 Upgrade Required 错误。

角色优先级

当用户属于同一工作区的多个群组时，适用以下优先级：

  1. Organization Admin 群组 优先级最高。这些群组中的用户将在所有工作区中是 Admin。
  2. 最近创建的工作区专属群组 优先于其他工作区群组。

NOTE

当一个群组被删除、或一个用户从群组移除时，他们的访问会依据其剩余的群组成员资格更新，遵循那些优先级规则。

SCIM 群组成员资格会覆盖手动指派的、或通过即时（JIT）预配指派的角色。我们建议禁用 JIT 预配以避免冲突。更多细节，参阅管理 SSO 组织中的用户访问。

邮箱验证

仅在云上，用 SCIM 创建一个新用户会触发一封给用户的邮件。 他们必须通过点击这封邮件中的链接来验证其邮箱地址。 该链接 24 小时后过期，并可通过移除并重新用 SCIM 添加该用户来重发（如果需要）。

属性与映射

群组命名约定

WARNING

通过 SCIM 不支持重命名群组。群组名是持久的，因为它们必须匹配 LangSmith 中的角色名和/或工作区名。

群组成员资格用一个特定的命名约定映射到 LangSmith 工作区成员资格和工作区角色。默认地，各部分之间的分隔符是冒号（:），但你能为你组织配置一个自定义分隔符。

NOTE

你能省略群组名中组织角色名那部分的空格。这有助于不允许群组名含空格的身份提供商。例如，LangSmith 接受 OrganizationAdmins 和 OrganizationUser 作为 Organization Admins 和 Organization User 的等价形式。这一灵活性仅适用于组织角色名这个记号。工作区名和工作区角色名把空格当作字面字符，所以省略空格的变体不会与它们带空格的对应形式匹配。

Organization Admin 群组

格式：<optional_prefix>Organization Admin 或 <optional_prefix>Organization Admins

示例：

  • LS:Organization Admins
  • LS:OrganizationAdmins（省略空格——对不允许群组名含空格的 IdP 有用）
  • Groups-Organization Admins
  • Organization Admin

工作区专属群组

格式：<optional_prefix><org_role_name><separator><workspace_name><separator><workspace_role_name>

分隔符默认为 :（冒号）。受支持的分隔符有：:（冒号）、-（连字符）、_（下划线）、（空格）、&（与号）。

带默认冒号分隔符的例子：

  • LS:Organization User:Production:Annotators
  • LS:OrganizationUser:Production:Annotators（角色名记号中省略空格）
  • Groups-Organization User:Engineering:Developers
  • Organization User:Marketing:Viewers

带连字符分隔符的例子：

  • LS-Organization User-Production-Annotators
  • LS-OrganizationUser-Production-Annotators（角色名记号中省略空格）
  • Organization User-Engineering-Developers

NOTE

如果你的工作区名含分隔符字符（例如工作区 my-team 配分隔符 -），LangSmith 会自动尝试所有可能的拆分以找到一个有效的工作区和角色组合。

配置自定义分隔符

要更改你组织的 SCIM 群组名分隔符，用 PATCH /api/v1/orgs/current/info 端点。对于区域 SaaS 部署，把请求发送到区域主机上的同一路径（eu.api.smith.langchain.com、apac.api.smith.langchain.com，或 aws.api.smith.langchain.com）：

bash
curl -X PATCH $LANGCHAIN_ENDPOINT/api/v1/orgs/current/info \
  -H "X-Api-Key: $LANGCHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scim_group_name_separator": "-"}'

分隔符必须是一个字符，且是以下之一：:（冒号）、-（连字符）、_（下划线）、（空格），或 &（与号）。默认为 :（冒号）。

NOTE

更改分隔符不会重命名现有的 SCIM 群组。若你更改了分隔符，你也必须更新你身份提供商中的群组名以使用新分隔符。

映射

虽然依身份提供商而不同的具体说明可能变化，这些映射展示 LangSmith SCIM 集成支持什么：

用户属性

LangSmith 应用属性身份提供商属性匹配优先级
userName1email address
active!deactivated
emails[type eq "work"].valueemail address2
name.formatteddisplayName OR givenName + familyName3
givenNamegivenName
familyNamefamilyName
externalIdsub41
  1. LangSmith 不要求 userName
  2. 邮箱地址是必需的
  3. 若你的 displayName 不匹配 Firstname Lastname 格式，用那个计算表达式
  4. 为避免不一致，对云客户这应当匹配 SAML NameID 断言，对自托管匹配 sub OAuth2.0 声明。

群组属性

LangSmith 应用属性身份提供商属性匹配优先级
displayNamedisplayName11
externalIdobjectId
membersmembers
  1. 群组必须遵循群组命名约定一节中描述的命名约定。 若你公司有群组命名策略，你应当改从 description 身份提供商属性映射，并 依据群组命名约定一节设置描述。

步骤 1 - 配置 SAML SSO（仅云）

SAML SSO 配置有两种情形：

  1. 若 SAML SSO 已为你组织配置，你应当跳过初次添加应用的步骤（从 Okta Integration Network 添加应用 或 创建一个新的 Entra ID 应用集成），因为你已配好一个应用、只需启用预配。
  2. 若你首次配置 SAML SSO 并连同 SCIM 一起，先遵循说明设置 SAML SSO，然后遵循这里的说明启用 SCIM。

NameID 格式

LangSmith 用 SAML NameID 来识别用户。NameID 是 SAML 响应中的一个必需字段，且不区分大小写。

NameID 必须：

  1. 对每个用户唯一。
  2. 是一个永不改变的持久值，例如一个随机生成的唯一用户 ID。
  3. 在每次登录尝试上精确匹配。它不应依赖用户输入。

NameID 不应是邮箱地址或用户名，因为邮箱地址和用户名更可能随时间改变且可能区分大小写。

NameID 格式必须是 Persistent，除非你用一个如邮箱那样需要不同格式的字段。

步骤 2 - 禁用 JIT 预配

在启用 SCIM 之前，禁用即时（JIT）预配，以防止自动与手动用户预配之间的冲突。

为云禁用 JIT

用 PATCH /orgs/current/info 端点。对于区域 SaaS 部署，把请求发送到区域主机上的同一路径（eu.api.smith.langchain.com、apac.api.smith.langchain.com，或 aws.api.smith.langchain.com）：

bash
curl -X PATCH $LANGCHAIN_ENDPOINT/orgs/current/info \
  -H "X-Api-Key: $LANGCHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jit_provisioning_enabled": false}'

为 Self-Hosted 禁用 JIT

从 LangSmith chart 版本 0.11.14 起，你能用 SSO 为你的自托管组织禁用 JIT 预配。要禁用，设以下值：

yaml
commonEnv:
  - name: SELF_HOSTED_JIT_PROVISIONING_ENABLED
    value: "false"

步骤 3 - 生成 SCIM bearer 令牌

NOTE

在自托管环境中，下面完整的 URL 可能形如 https://langsmith.yourdomain.com/api/v1/platform/orgs/current/scim/tokens（无子域，注意 /api/v1 路径前缀）或 https://langsmith.yourdomain.com/subdomain/api/v1/platform/orgs/current/scim/tokens（带子域）——更多细节见 ingress 文档。

为你的组织生成一个 SCIM Bearer 令牌。你的 IdP 会用这个令牌对 SCIM API 请求身份验证。确保环境变量恰当设置，例如：

bash
curl -X POST $LANGCHAIN_ENDPOINT/v1/platform/orgs/current/scim/tokens \
  -H "X-Api-Key: $LANGCHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Your description here"}'

注意 SCIM Bearer 令牌的值在此请求的响应之外不可获取。存在这些额外端点：

  • GET /v1/platform/orgs/current/scim/tokens
  • GET /v1/platform/orgs/current/scim/tokens/{scim_token_id}
  • PATCH /v1/platform/orgs/current/scim/tokens/{scim_token_id}（只支持 description 字段）
  • DELETE /v1/platform/orgs/current/scim/tokens/{scim_token_id}

步骤 4 - 配置你的身份提供商

NOTE

如果你用 Azure Entra ID（前 Azure AD）或 Okta，有关于身份提供商设置的专门说明（参阅 Azure Entra ID、Okta）。上面的要求和步骤适用于所有身份提供商。

Azure Entra ID 配置步骤

更多信息，见 Microsoft 的文档。

NOTE

在自托管安装中，oid JWT 声明被用作 sub。 见这个 Microsoft Learn 链接 和相关配置说明以了解更多细节。

步骤 1：在你的 Enterprise Application 中配置 SCIM

  1. 用一个特权角色（例如 Global Administrator）登录 Azure 门户。
  2. 导航到你现有的 LangSmith Enterprise Application。
  3. 在左侧导航，选择 Manage > Provisioning。
  4. 点击 Get started。

步骤 2：配置管理员凭据

  1. 在 Admin Credentials 下：

    • Tenant URL：

      Region Host / URL
      GCP US {`$ / https://${prefix_10 || "api.smith"}.langchain.com${suffix_10 || ""}`}
      GCP EU {`$ / https://eu.${prefix_10 || "api.smith"}.langchain.com${suffix_10 || ""}`}
      GCP APAC {`$ / https://apac.${prefix_10 || "api.smith"}.langchain.com${suffix_10 || ""}`}
      AWS US {`$ / https://aws.${prefix_10 || "api.smith"}.langchain.com${suffix_10 || ""}`}
      • 自托管：<langsmith_url>/scim/v2

    • Secret Token：输入步骤 3 中生成的 SCIM Bearer 令牌。

  2. 点击 Test Connection 验证配置。

  3. 点击 Save。

步骤 3：配置属性映射

在 Mappings 下配置以下属性映射：

用户属性

把 Target Object Actions 设为 Create 和 Update（出于安全先禁用 Delete）：

LangSmith 应用属性Microsoft Entra ID 属性匹配优先级
userNameuserPrincipalName
activeNot([IsSoftDeleted])
emails[type eq "work"].valuemail1
name.formatteddisplayName OR Join(" ", [givenName], [surname])2
externalIdobjectId31
  1. 用户的邮箱地址必须在 Entra ID 中存在。
  2. 若你的 displayName 不匹配 Firstname Lastname 格式，用 Join 表达式。
  3. 为避免不一致，这应当匹配 SAML NameID 断言和 sub OAuth2.0 声明。对于云中的 SAML SSO，Unique User Identifier (Name ID) 必需声明应为 user.objectID，且 Name identifier format 应为 persistent。

群组属性

把 Target Object Actions 设为仅 Create 和 Update（出于安全先禁用 Delete）：

LangSmith 应用属性Microsoft Entra ID 属性匹配优先级
displayNamedisplayName11
externalIdobjectId
membersmembers
  1. 群组必须遵循群组命名约定一节中描述的命名约定。 若你公司有群组命名策略，你应当改从 description Microsoft Entra ID 属性映射，并 依据群组命名约定一节设置描述。

步骤 4：指派用户和群组

  1. 在 Applications > Applications 下，选择你的 LangSmith Enterprise Application。
  2. 在 Assignments 标签下，点击 Assign，然后 Assign to People 或 Assign to Groups。
  3. 做所需的选择，然后 Assign 和 Done。

步骤 5：启用预配

  1. 在 Provisioning 下把 Provisioning Status 设为 On。
  2. 监控初始同步，确保用户和群组被正确预配。
  3. 一旦验证，为用户和群组映射都启用 Delete 动作。

关于故障排除，参阅 SAML SSO 常见问题。如果设置 SCIM 时遇到问题，通过 support.langchain.com 联系 LangChain 支持团队。

Okta 配置步骤

NOTE

你必须使用 Okta Lifecycle Management 产品。要在 Okta 上用 SCIM 需要这个产品档。

支持的功能
  • 创建用户
  • 更新用户属性
  • 停用用户
  • 群组推送（不带群组重命名）
  • 导入用户
  • 导入群组
步骤 1：从 Okta Integration Network 添加应用

NOTE

如果你已通过 SAML（云）或 OAuth2.0 带 OIDC（自托管）配置了 SSO 登录，跳过这一步。

云见 SAML SSO 设置，自托管见 OAuth2.0 设置。

步骤 2：配置 API 集成

  1. 在 General 标签中，确保 LangSmithUrl 依步骤 1的说明填好
  2. 在 Provisioning 标签中，选择 Integration。
  3. 选择 Edit，然后 Enable API integration。
  4. 对于 API Token，粘贴你上面生成的 SCIM 令牌。
  5. 保持 Import Groups 勾选。
  6. 要验证配置，选择 Test API Credentials。
  7. 选择 Save。
  8. 保存 API 集成详情后，左侧会出现新的设置标签。选择 To App。
  9. 选择 Edit。
  10. 为 Create Users、Update Users 和 Deactivate Users 勾选 Enable 复选框。
  11. 选择 Save。
  12. 在 Assignments 标签中指派用户和/或群组。被指派的用户会在你的 LangSmith 群组中被创建和管理。

步骤 3：配置用户预配设置

  1. 配置预配：在 Provisioning > To App > Provisioning to App 下，点击 Edit，然后勾选 Create Users、Update User Attributes 和 Deactivate Users。
  2. 在 <application_name> Attribute Mappings 下，按下图设置用户属性映射，并删除其余：
SCIM Okta User Attributes Mapping

步骤 4：推送群组

NOTE

Okta 除群组名本身之外不支持群组属性，所以群组名 必须 遵循群组命名约定一节中描述的命名约定。

遵循 Okta 的启用群组推送说明确，按名或按规则配置要推送的群组。

用自定义 SAML 应用配置 SCIM

如果你已经通过一个自定义 SAML 应用登录，你有两个选项。

仅为 SCIM 添加 Okta Integration Network 应用（推荐）。 从 Okta Integration Network 添加 LangSmith 应用，然后遵循上面步骤 2 到 4。步骤 1 说 SSO 配置好后跳过它，但 SCIM 需要该应用，所以无论如何都要添加它。别动它的 SAML 设置：你的自定义应用继续处理登录。在 Application Visibility 下，勾选 Do not display application icon to users，这样就不会给用户显示一个无法让他们登录的磁贴。

在你的自定义应用上启用 SCIM。 在 General > App Settings 下，把 Provisioning 设为 SCIM。然后在 Provisioning > Integration 下，配置：

  • SCIM connector base URL：

    区域 主机 / URL
    GCP US {`$ / https://${prefix_11 || "api.smith"}.langchain.com${suffix_11 || ""}`}
    GCP EU {`$ / https://eu.${prefix_11 || "api.smith"}.langchain.com${suffix_11 || ""}`}
    GCP APAC {`$ / https://apac.${prefix_11 || "api.smith"}.langchain.com${suffix_11 || ""}`}
    AWS US {`$ / https://aws.${prefix_11 || "api.smith"}.langchain.com${suffix_11 || ""}`}

  • 用户唯一标识符字段：userName

  • 支持的预配动作：Push New Users、Push Profile Updates、Push Groups、Import Groups

  • 身份验证模式：HTTP Header，用你上面生成的 SCIM 令牌

这些设置替代步骤 2 的 API 集成。从该步骤的 To App 设置继续：启用 Create Users、Update Users 和 Deactivate Users，然后指派你的用户和群组。步骤 3 和 4 讲述属性映射和群组推送。

NOTE

如果 Provisioning 不出现在你应用的设置中，检查你组织是否有 Okta Lifecycle Management，Okta 对 SCIM 预配需要它。如果你有它而该选项仍缺失，联系 Okta 以启用它。

其他身份提供商

其他身份提供商未经测试，但依其 SCIM 实现或许能用。

SSO Groups Sync（替代方案）

NOTE

SSO Groups Sync 对配置了 SAML SSO（云）或 OIDC（自托管）的、处于 Enterprise 方案 的组织可用。联系我们的销售团队以了解更多。

SSO Groups Sync 是一个比 SCIM 更简单的替代方案，适合不能或不愿配置 SCIM 群组推送的组织。与其在一个单独同步间隔从你的 IdP 把群组推送到 LangSmith，LangSmith 在登录时从一个可配置声明直接在 SSO 令牌读群组成员资格，并用与 SCIM 相同的命名约定应用组织级和工作区级角色指派。

何时用 SSO Groups Sync 对用 SCIM

SSO Groups Sync 和 SCIM 技术上能共存（各自只管理带其自身预配方法标记的身份），但我们推荐每个组织选一种机制，而非两者都用，以避免混乱的优先级行为。

SSO Groups SyncSCIM
同步触发在每次 SSO 登录从 IdP 主动推送（~1 小时节奏）
IdP 管理员介入极少，只需把群组含入 SSO 令牌必需，配置 SCIM 预配应用
去配滞后直到下次登录通过 IdP 推送近实时
命名约定复用 SCIM 约定SCIM 约定
自定义分隔符复用组织级 scim_group_name_separatorscim_group_name_separator

当 IdP 管理员介入极少、且被动（登录时）同步可接受时，选 SSO Groups Sync。当需要主动预配/去配和近实时的群组成员资格更新时，选 SCIM。

配置

  1. 在你的 IdP 中：把用户的群组成员资格加到 SSO 令牌声明（默认声明名：groups）。群组名必须遵循 SCIM 命名约定。

  2. 在 LangSmith 中：前往 Settings > Members and roles > SSO Configuration > SSO Groups Sync 并配置以下：

    设置描述
    Enable SSO Groups Sync依据 SSO 令牌中的群组成员资格自动指派工作区角色。
    Groups claim field（默认 groups）SSO 令牌中含群组成员资格的那个声明名。
    Sync workspace/role assignments在每次 SSO 登录时从群组名更新工作区成员资格和角色。
    Require matching group to sign in若 SSO 令牌不含匹配命名的群组则阻止登录。

你也能通过向 SSO 设置端点发一个 PATCH，用 API 配置这些设置：

bash
curl -X PATCH $LANGCHAIN_ENDPOINT/api/v1/orgs/current/sso-settings/$SSO_PROVIDER_ID \
  -H "X-Api-Key: $LANGCHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sso_groups_enabled": true,
    "sso_groups_claim_field": "groups",
    "sso_groups_role_sync_enabled": true,
    "sso_groups_required": false
  }'

WARNING

禁用 SSO Groups Sync 不会移除现有访问。由 SSO 群组预配的用户会保留其当前访问直到下次登录。

配置你的 IdP 发出一个 groups SAML 属性（云）

NOTE

本节仅适用于企业云。自托管客户直接在其 OIDC IdP 中配置群组，见自托管上的 SSO Groups Sync。

要在登录时让用户群组成员资格对 LangSmith 可见，你需要做两件事：

  1. 配置你 IdP 的 SAML 应用以发出一个多值群组属性。
  2. 向 SAML 属性映射添加一个匹配条目，好让该属性流到 JWT（勾选 Array）。

要求：

  • IdP 属性名（例如 groups）必须同时匹配 SAML Attribute Mapping 条目和 Groups claim field 值（默认 groups）。
  • 该属性必须是多值的（一个字符串列表），而非单个分隔字符串。若你的 IdP 只支持单值属性，你得为每个群组发一个属性声明。
  • 每个值必须是遵循 SCIM 命名约定的群组名。
  • 只处理名字匹配该约定的群组。LangSmith 忽略不匹配其命名约定的群组，如组织级目录群组或应用指派群组。你不需要在 IdP 侧过滤掉它们——发出所有群组，LangSmith 会跳过无关的那些。

按 IdP 的设置：

在 LangSmith SAML 应用中：

  1. 前往 Directory > Profile Editor，然后选择 LangSmith 应用的用户配置文件。
  2. 添加一个名为 groups、Type 为 string array 的自定义属性。
  3. 在 Sign On 上，编辑 SAML 设置并添加一个属性声明：
    • Name：groups
    • Name format：Unspecified（或 Basic）
    • Filter：Matches regex 配 .* 发送所有群组，或用一个更严格的正则（例如 ^LS:.*）限定到 LangSmith 前缀群组。

群组命名例子

群组名遵循 SCIM 命名约定。<workspace_role> 段既接受内置角色，也按名接受自定义工作区角色。

意图群组名例子
组织管理员（在所有工作区授予工作区管理员）LS:Organization Admins
在 Production 中的工作区管理员LS:Organization User:Production:Admin
在 Engineering 中的工作区编辑器LS:Organization User:Engineering:Editor
在 Marketing 中的工作区查看者LS:Organization User:Marketing:Viewer
在 Production 中的自定义角色 AnnotatorsLS:Organization User:Production:Annotators

行为

  • 命名约定：群组名遵循与 SCIM 相同的格式（例如组织管理员用 LS:Organization Admins，工作区级用 LS:Organization User:Production:Editor）。完整格式见群组命名约定。分隔符按组织经 scim_group_name_separator 配置，并与 SCIM 共享。
  • 畸形的群组名：不匹配该约定的群组名被静默跳过（记日志）且不阻止有效群组的登录。
  • 登录闸门：当 Require matching group to sign in 启用且 SSO 令牌含零个匹配群组时，登录被阻止。
  • 优先级：SSO Groups Sync 不修改 SCIM 来源、手动指派、或 JIT 预配的成员的成员资格。它对自己的指派完全权威，并在每次登录依据令牌的群组成员资格替换它们。
  • 组织管理员传播：若一个用户从其群组获得一个组织管理员角色，他们在所有工作区被授予工作区管理员（与 SCIM 行为相同）。

需要注意的事项

  • 去配滞后：与 SCIM（主动推送）不同，SSO Groups Sync 只在登录时更新。一个在 IdP 中被从群组移除的用户，会保留其现有工作区访问直到下次 LangSmith 登录。Require matching group to sign in 闸门通过在下次登录完全阻止该用户来缓解这一点。
  • 无追溯同步：更改角色映射或启用该功能，不会在现有用户再次登录之前更新他们。
  • 需要命名约定：客户必须遵循 SCIM 约定为其 IdP 群组命名。若你的 IdP 群组遵循不同的命名策略，用基于 description 映射的 SCIM（见群组属性）或许更合适。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可