LangSmith 自托管版 通过 OAuth2.0 和 OIDC 提供 SSO,它将认证委托给您的身份提供商 (IdP) 来管理对 LangSmith 的访问。 LangSmith 的实现支持任何符合 OIDC 标准的提供者。配置完成后,您将看到一个登录屏幕,提示 通过 SSO 登录。 默认情况下,LangSmith 自托管版支持带 客户端密钥 的 授权码 流程。在此流程版本中,您的客户端密钥安全地存储在 LangSmith(不在前端)中,并用于认证和建立认证会话。

注意事项

  • 您可以将 basic 认证 安装升级到 oauth 模式,但不能将 none 认证 安装进行升级。
  • LangSmith 不 支持:
    • 在自托管版中从 SSO 切换回 basic 认证模式。
    • 在带客户端密钥的 OAuth 模式和不带客户端密钥的 OAuth 模式之间相互切换。
    • 同时启用 basic 认证和 OAuth。启用 OAuth 时请确保禁用 basic 认证配置。

前提条件

要完成 提供者设置,您必须具备以下条件:
  • 自托管版 并且使用 企业版计划。
  • 一个支持带 客户端密钥 的 授权码 流程的身份提供商。
  • 一个支持使用外部发现/颁发者 URL 的身份提供商。LangSmith 使用此 URL 来获取您的身份提供商所需的路由和密钥。
  • OIDC、email 和 profile 作用域。LangSmith 使用这些来获取用户所需的信息和电子邮件。
LangSmith SSO 仅支持 https。

配置

  • 您需要将身份提供商中的回调 URL 设置为 https://<host>/api/v1/oauth/custom-oidc/callback,其中 host 是您为 LangSmith 实例配置的域名或 IP。身份提供商将在用户完成认证后重定向到此地址。
  • 要在登出时终止身份提供商会话(以便用户必须重新认证),请将您的 LangSmith URL(例如 https://<host>)注册为身份提供商中的登出后重定向 URI(有时称为“签出重定向 URI”),然后在 Helm 中通过 commonEnv 在您的环境中设置 OAUTH_IDP_LOGOUT_ENABLED=true。
  • 您需要在 values.yaml 文件中提供 oauthClientId、oauthClientSecret、hostname 和 oauthIssuerUrl。您将在此文件中配置您的 LangSmith 实例。
  • 如果您尚未配置带客户端密钥的 OAuth 或者您只有个人组织,则必须提供一个电子邮件地址,用作新配置的 SSO 组织的 initialOrgAdminEmail。如果您是从 basic auth 升级,LangSmith 将重用您现有的组织。
Helm

提供者设置

Microsoft Entra ID 身份提供商设置

使用 OAuth2.0 和 OIDC 将 Microsoft Entra ID 配置为单点登录提供者。更多信息,请参阅 Microsoft 的 OpenID Connect 文档。
在 Microsoft Entra ID 中注册应用程序需要在您的租户中具有 Application Administrator 或 Cloud Application Administrator 角色,或更高权限。

步骤 1. 注册应用程序

  1. 在 Microsoft Entra 管理中心 中,转到 应用程序 > 应用注册 > 新建注册。
  2. 将 名称 设置为标识应用程序的值,例如 LangSmith Self-Hosted。
  3. 将 支持的帐户类型 设置为 仅此组织目录中的帐户(单租户)。
  4. 在 重定向 URI 下,选择平台 Web,并输入 https://<host>/api/v1/oauth/custom-oidc/callback,其中 <host> 是您的 LangSmith 实例的域名。
  5. 点击 注册。
从应用的 概述 页面,记录以下值以用于 Helm 配置:
  • 应用程序(客户端)ID:用作 oauthClientId。
  • 目录(租户)ID:用于构造颁发者 URL。
  • OIDC 颁发者 URL:https://login.microsoftonline.com/<tenant-id>/v2.0,用作 oauthIssuerUrl。

步骤 2. 创建客户端密钥

  1. 在应用注册中,转到 证书和密钥 > 客户端密钥 > 新建客户端密钥。
  2. 输入描述,选择过期时间,然后点击 添加。
  3. 立即复制密钥 值。Microsoft Entra ID 在您离开页面后会隐藏此值。将其用作 oauthClientSecret。
在配置 Helm 之前,将客户端 ID、客户端密钥和颁发者 URL 存储在您的密钥存储中。

步骤 3. 添加电子邮件可选声明

如果没有此步骤,LangSmith 会阻止登录并显示错误 Your identity provider did not provide an email address。
  1. 在应用注册中,转到 令牌配置 > 添加可选声明。
  2. 选择令牌类型为 ID。
  3. 勾选 email,然后点击 添加。
  4. 当提示时,接受授予 Microsoft Graph email 权限的请求。

步骤 4. 配置 LangSmith

将前几步中的值应用到您的 Helm 配置:
Helm
有关 initialOrgAdminEmail 的详细信息,请参阅 常规配置部分。
默认情况下,Microsoft Entra ID 的 oid 声明用作 OIDC sub 声明。详细信息,请参阅 覆盖 sub 声明。
要在登录时从 Microsoft Entra ID 组分配组织和工作区角色,请参阅 SSO 组同步。

Google Workspace 身份提供商设置

您可以使用 OAuth2.0 和 OIDC 将 Google Workspace 用作单点登录 (SSO) 提供者,但不支持 PKCE。
您必须对组织的 Google Cloud Platform (GCP) 帐户具有管理员级访问权限,才能创建新项目,或具有为现有项目创建和配置 OAuth 2.0 凭据的权限。我们建议您为管理访问权限创建一个新项目,因为每个 GCP 项目只有一个 OAuth 同意屏幕。
  1. 创建一个新的 GCP 项目,参见 Google 文档主题 创建和管理项目
  2. 创建项目后,打开 凭据 页面(确保左上角的项目正确)
  3. 创建新凭据:创建凭据 → OAuth 客户端 ID
  4. 选择 Web 应用程序 作为 应用程序类型,并为应用程序输入一个名称,例如 LangSmith
  5. 在 已获授权的 JavaScript 来源 中放入您的 LangSmith 实例的域名,例如 https://langsmith.yourdomain.com
  6. 在 已获授权的重定向 URI 中放入您的 LangSmith 实例域名后跟 /api/v1/oauth/custom-oidc/callback,例如 https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback
  7. 点击 创建,然后下载 JSON 或复制并保存 Client ID(以 .apps.googleusercontent.com 结尾)和 Client secret 到安全的地方。如果需要,您稍后可以访问这些信息。
  8. 从左侧导航菜单中选择 OAuth consent screen
    1. 选择应用程序类型为 Internal。如果选择 Public,任何拥有 Google 帐户的人都可以登录。
    2. 输入描述性的 Application name。此名称在用户登录时显示在同意屏幕上。例如,使用 LangSmith 或 <organization_name> SSO for LangSmith。
    3. 确认 Google API 的 Scopes 仅列出了 email、profile 和 openid 作用域。单点登录只需要这些作用域。如果您授予额外的作用域,会增加暴露敏感数据的风险。
  9. (可选)控制组织中谁有权访问 LangSmith:https://admin.google.com/ac/owl/list?tab=configuredApps。更多详情请参阅 Google 文档。
  10. 配置 LangSmith 以使用此 OAuth 应用程序。例如,以下是用于 Kubernetes 配置的 config 值:
    1. oauthClientId: Client ID(以 .apps.googleusercontent.com 结尾)
    2. oauthClientSecret: Client secret
    3. hostname: 您的 LangSmith 实例的域名,例如 https://langsmith.yourdomain.com(无尾随斜杠)
    4. oauthIssuerUrl: https://accounts.google.com
    5. oauth.enabled: true
    6. authType: mixed

Okta 身份提供商设置

支持的功能

配置步骤

更多信息,请参阅 Okta 的 文档。 如有任何问题或疑问,请通过 support.langchain.com 联系支持。
通过 Okta 集成网络(推荐)
有关 SCIM 设置的详细信息,请参阅 为您的组织设置 SCIM。
要使用 SCIM 与 Okta,必须使用此配置方法。
  1. 登录 Okta。
  2. 在右上角,选择 Admin。该按钮在 Admin 区域不可见。
  3. 选择 浏览应用集成目录。
  4. 查找并选择 LangSmith 应用程序。
  5. 在应用程序概述页面上,选择添加集成。
  6. 填写 ApiUrlBase:
    • 您的 LangSmith API URL,不带协议 (https://),格式为 <langsmith_domain>/api/v1,例如 langsmith.yourdomain.com/api/v1。
    • 如果您的安装配置了子域 / 路径前缀,请将其包含在 URL 中,例如 langsmith.yourdomain.com/prefix/api/v1。
  7. 将 AuthHost 留空。
  8. (可选,如果计划同时使用 SCIM)填写 LangSmithUrl:上面的 <langsmith_url> 部分,例如 langsmith.yourdomain.com。
  9. 在应用程序可见性下,保持复选框未选中。
  10. 选择下一步。
  11. 选择 OpenID Connect。
  12. 填写 登录选项:
    • 应用程序用户名格式:Email。
    • 更新应用程序用户名时机:创建和更新时。
    • 允许用户安全地查看其密码:保持未选中。
  13. 点击 保存。
  14. 配置 LangSmith 以使用此 OAuth 应用程序(有关 initialOrgAdminEmail 的详细信息,请参阅 常规配置部分):
Helm
有关 SCIM 设置的详细信息,请参阅 为您的组织设置 SCIM。
通过自定义应用集成
SCIM 与此配置方法不兼容。请参阅 通过 Okta 集成网络。
  1. 以管理员身份登录 Okta,然后进入 Okta 管理控制台。
  2. 在 应用程序 > 应用程序 下,点击 创建应用集成。
  3. 选择 OIDC - OpenID Connect 作为登录方法,Web 应用程序 作为应用程序类型,然后点击 下一步。
  4. 输入 应用集成名称(例如 LangSmith)。
  5. 建议:勾选 核心授权 > 刷新令牌(参见 会话长度控制)。
  6. 在 登录重定向 URI 中,放入您的 LangSmith 实例域名后跟 /api/v1/oauth/custom-oidc/callback,例如 https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback。如果您的安装配置了子域 / 路径前缀,请将其包含在 URL 中,例如 https://langsmith.yourdomain.com/prefix/api/v1/oauth/custom-oidc/callback。
  7. 在 登出重定向 URI 下,将值设置为您的 LangSmith URL,例如 https://langsmith.yourdomain.com。这确保当用户登出 LangSmith 时,IdP 会话将被终止。
  8. 在 受信任的来源 > 基础 URI 下,添加您的 LangSmith URL(带协议),例如 https://langsmith.yourdomain.com。
  9. 在 分配 > 受控访问 下选择您想要的选项:
    • 允许组织中的每个人访问。
    • 限制对选定组的访问。
    • 现在跳过组分配。
  10. 点击 保存。
  11. 在 登录 > OpenID Connect ID 令牌 下,将 颁发者 设置为 Okta URL。
  12. (可选)在 常规 > 登录 下,将 登录发起方 设置为 Okta 或应用均可以,以启用 IdP 发起的登录。
  13. (建议)在 常规 > 登录 > 电子邮件验证体验 下,在 回调 URI 中填写 LangSmith URL,例如 https://langsmith.yourdomain.com。
  14. 配置 LangSmith 以使用此 OAuth 应用程序(有关 initialOrgAdminEmail 的详细信息,请参阅 常规配置部分):
Helm

SP 发起的 SSO

用户可以在 LangSmith 主页上使用 通过 SSO 登录 按钮登录。

高级选项

会话长度控制

本节中的所有环境变量都适用于 platform-backend 服务,可以通过 Helm 中的 platformBackend.deployment.extraEnv 添加。
  • 默认情况下,会话长度由身份提供商返回的身份令牌过期时间控制。
  • 大多数设置应使用刷新令牌来将会话长度扩展到超过身份令牌过期时间,最长可至 OAUTH_SESSION_MAX_SEC,这可能需要通过在 Helm 中的 oauthScopes 中添加 offline_access 作用域。
  • OAUTH_SESSION_MAX_SEC(默认 1 天)可以覆盖为最多一周(604800)。
  • 对于不支持刷新令牌的身份提供商设置,将 OAUTH_OVERRIDE_TOKEN_EXPIRY="true" 设置为使用 OAUTH_SESSION_MAX_SEC 作为会话长度,忽略身份令牌过期时间。

严格身份提供商的作用域编码

默认情况下,LangSmith 在授权请求中将 oauthScopes 之间的空格编码为 +(application/x-www-form-urlencoded 约定)。大多数身份提供商接受这种编码,但有些(例如 CA SiteMinder)不会将 + 解码为空格,并会以 invalid_scope 错误拒绝登录。如果您的身份提供商因此原因拒绝多作用域登录,请在 Helm 中设置 urlEncodeScopeSpaces: true,以将空格编码为 %20(这是所有符合 OIDC 的提供者都接受的编码)。这仅适用于带 OAuth 客户端密钥的 authType: mixed,默认为关闭。
Helm

覆盖 sub 声明

在某些情况下,可能需要覆盖身份提供商中用作 sub 声明的声明。 例如,在 SCIM 中,解析后的 sub 声明和 SCIM externalId 必须匹配才能成功登录。 如果对 sub 声明的源属性和/或 SCIM externalId 有限制,请设置 ISSUER_SUB_CLAIM_OVERRIDES 环境变量以选择哪个 OIDC JWT 声明用作 sub。 如果颁发者 URL 以此配置中的某个 URL 开头,则 sub 声明取自指定的字段名。 例如,使用以下配置,颁发者为 https://idp.yourdomain.com/application/uuid 的令牌将使用 customClaim 值作为 sub:
如果未设置,此配置的默认值在使用 Azure Entra ID 作为身份提供商时使用 oid 声明:

SSO 组同步

自托管版的 SSO 组同步需要 LangSmith 图表版本 0.15.0-rc.3(应用程序版本 0.15.2rc1)或更高版本。
SSO 组同步 允许 LangSmith 从 OIDC 令牌上的组成员声明分配组织和工作区角色,作为 SCIM 的更简单替代方案。在自托管版上,您必须在 LangSmith 能够读取它们之前,将 IdP 配置为在 OIDC ID 令牌中包含组。 IdP 侧配置(因提供者而异):
  1. 配置您的 IdP 应用程序在 OIDC ID 令牌中发出组成员声明。源属性和生成的声明名称因 IdP 而异。常见示例包括 groups、roles 或自定义声明名称。LangSmith 不限定源属性。
  2. 根据您的 IdP,您可能需要将额外的作用域(通常是 groups)添加到 oauthScopes 以接收该声明。请查阅您的 IdP 文档以了解所需的作用域以及将组成员包含在令牌中所需的任何其他配置。
  3. 组名称必须遵循 SCIM 命名约定(例如 LS:Organization Admin、LS:Organization User:prod:Editor)。分隔符与 SCIM 通过 scim_group_name_separator 共享。
Helm 配置: 如果您的 IdP 需要额外的 OIDC 作用域才能在令牌中包含组(通常是 groups),请将其添加到 oauthScopes:
Helm
确切的作用域名称(groups、roles 等)取决于您的 IdP。请查阅您的 IdP 的 OIDC 文档。 LangSmith 侧配置: 每个提供者的 SSO 组同步设置存储在 SSO 提供者记录上,并通过 LangSmith UI 或 API 切换(不通过 Helm 值)。
一旦您的 IdP 发出组声明,可以从 UI 在 设置 → 成员和角色 → SSO 配置 → SSO 组同步 中配置 SSO 组同步。在 Groups claim field 中配置的声明名称必须与您的 IdP 发出的声明匹配。

从 Microsoft Entra ID 发出组声明

对于自托管版的 OIDC,请通过应用注册清单添加组声明。跳过 令牌配置 > 添加组声明 流程,该流程不支持仅云安全组的显示名称。
将顶级 groupMembershipClaims 属性设置为 "ApplicationGroup"。其他值会以难以诊断的方式改变行为:
  • 缺失或 "None":令牌中没有出现组。
  • "SecurityGroup" 或 "All":组会出现,但 cloud_displayname 值被静默忽略,令牌包含的是组对象 ID 而不是名称。
  • "ApplicationGroup":组解析为显示名称,但仅适用于在 用户和组 下明确分配给企业应用程序的组。 cloud_displayname 值仅受单租户应用程序支持。
在 应用注册 > 您的应用 > 清单 中,将以下内容合并到清单中,保留任何现有的 optionalClaims.idToken 条目,例如 email:
然后,在 企业应用程序 > 您的应用 > 用户和组 中,分配每个映射到 LangSmith 角色的组。未分配给企业应用程序的组不会出现在令牌中。

为 SSO 组同步创建 Microsoft Entra ID 组

用于 SSO 组同步的组必须遵循主用户管理页面上记录的 组命名约定(例如 LS:Organization Admins、LS:Organization User:Production:Editor)。组名称区分大小写,并且必须完全匹配该约定。 要在 Microsoft Entra ID 中创建组:
  1. 在 Microsoft Entra 管理中心,转到 组 > 新建组。
  2. 将 组类型 设置为 Security。
  3. 将 成员身份类型 设置为 Assigned(不支持动态成员身份)。
  4. 将 组名 设置为符合命名约定的值。
  5. 添加成员,然后点击 创建。
组成员身份的变更将在每个用户的下次登录时生效。

验证令牌中的组声明

完成 IdP 侧配置后,验证 OIDC ID 令牌是否包含预期的组声明:
  1. 从 LangSmith 登出,然后通过 SSO 重新登录。
  2. 在浏览器的开发者工具中,转到 Application > Cookies,找到 OAuth 会话 cookie。
  3. 使用 JWT 解码器(例如 jwt.io)解码 ID 令牌,并确认 groups 声明包含显示名称,而不是对象 ID:
如果声明包含 UUID 而不是名称,请重新检查清单中的 groupMembershipClaims 值,并确认组已在 用户和组 下分配给企业应用程序。

PKCE 流程(已弃用)

我们建议使用 客户端密钥 运行。但是,如果您的身份提供商不支持此方式,您可以使用 带 PKCE 的授权码 流程。
PKCE 工作流程自 v16 起已弃用,并将在 v17 中完全移除。将提供从 PKCE 到带客户端密钥的 OAuth 的迁移路径。我们建议尽快迁移到 客户端密钥流程。

要求

此流程不需要 客户端密钥。
将 OAuth SSO 与 LangSmith 配合使用有几个要求:
  • 您的身份提供商必须支持 带 PKCE 的授权码 流程(例如 Google 不支持此流程,但请参见 上文 了解 Google 支持的替代配置)。这在您的 OAuth 提供者中通常显示为配置”单页应用程序 (SPA)”。
  • 您的身份提供商必须支持使用外部发现/颁发者 URL。我们将使用此 URL 来获取您的身份提供商所需的路由和密钥。
  • 您必须向 LangSmith 提供 OIDC、email 和 profile 作用域。我们使用这些来获取用户所需的信息和电子邮件。
  • 您需要将身份提供商中的回调 URL 设置为 http://<host>/oauth-callback,其中 host 是您为 LangSmith 实例配置的域名或 IP。身份提供商将在用户完成认证后重定向到此地址。
  • 您需要在 values.yaml 文件中提供 oauthClientId 和 oauthIssuerUrl。您将在此文件中配置您的 LangSmith 实例。
Helm