客户端密钥 的 授权码 流程。在此流程版本中,您的客户端密钥安全地存储在 LangSmith(不在前端)中,并用于认证和建立认证会话。
注意事项
- 您可以将
basic认证 安装升级到oauth模式,但不能将none认证 安装进行升级。- 通过移除
basic认证配置参数 并添加 带客户端密钥的 OAuth 配置参数 来升级basic认证安装。之后用户将只能通过 OAuth 登录。为了在升级后保持访问权限,您必须能够使用先前通过 basic auth 登录过的电子邮件地址通过 OAuth 登录。
- 通过移除
- LangSmith 不 支持:
- 在自托管版中从 SSO 切换回
basic认证模式。 - 在带客户端密钥的 OAuth 模式和不带客户端密钥的 OAuth 模式之间相互切换。
- 同时启用
basic认证和 OAuth。启用 OAuth 时请确保禁用basic认证配置。
- 在自托管版中从 SSO 切换回
前提条件
要完成 提供者设置,您必须具备以下条件:- 自托管版 并且使用 企业版计划。
- 一个支持带
客户端密钥的授权码流程的身份提供商。 - 一个支持使用外部发现/颁发者 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. 注册应用程序
- 在 Microsoft Entra 管理中心 中,转到 应用程序 > 应用注册 > 新建注册。
- 将 名称 设置为标识应用程序的值,例如
LangSmith Self-Hosted。 - 将 支持的帐户类型 设置为 仅此组织目录中的帐户(单租户)。
- 在 重定向 URI 下,选择平台 Web,并输入
https://<host>/api/v1/oauth/custom-oidc/callback,其中<host>是您的 LangSmith 实例的域名。 - 点击 注册。
- 应用程序(客户端)ID:用作
oauthClientId。 - 目录(租户)ID:用于构造颁发者 URL。
- OIDC 颁发者 URL:
https://login.microsoftonline.com/<tenant-id>/v2.0,用作oauthIssuerUrl。
步骤 2. 创建客户端密钥
- 在应用注册中,转到 证书和密钥 > 客户端密钥 > 新建客户端密钥。
- 输入描述,选择过期时间,然后点击 添加。
- 立即复制密钥 值。Microsoft Entra ID 在您离开页面后会隐藏此值。将其用作
oauthClientSecret。
步骤 3. 添加电子邮件可选声明
如果没有此步骤,LangSmith 会阻止登录并显示错误Your identity provider did not provide an email address。
- 在应用注册中,转到 令牌配置 > 添加可选声明。
- 选择令牌类型为 ID。
- 勾选
email,然后点击 添加。 - 当提示时,接受授予 Microsoft Graph
email权限的请求。
步骤 4. 配置 LangSmith
将前几步中的值应用到您的 Helm 配置:Helm
initialOrgAdminEmail 的详细信息,请参阅 常规配置部分。
默认情况下,Microsoft Entra ID 的
oid 声明用作 OIDC sub 声明。详细信息,请参阅 覆盖 sub 声明。Google Workspace 身份提供商设置
您可以使用 OAuth2.0 和 OIDC 将 Google Workspace 用作单点登录 (SSO) 提供者,但不支持 PKCE。您必须对组织的 Google Cloud Platform (GCP) 帐户具有管理员级访问权限,才能创建新项目,或具有为现有项目创建和配置 OAuth 2.0 凭据的权限。我们建议您为管理访问权限创建一个新项目,因为每个 GCP 项目只有一个 OAuth 同意屏幕。
- 创建一个新的 GCP 项目,参见 Google 文档主题 创建和管理项目
- 创建项目后,打开 凭据 页面(确保左上角的项目正确)
- 创建新凭据:
创建凭据 → OAuth 客户端 ID - 选择
Web 应用程序作为应用程序类型,并为应用程序输入一个名称,例如LangSmith - 在
已获授权的 JavaScript 来源中放入您的 LangSmith 实例的域名,例如https://langsmith.yourdomain.com - 在
已获授权的重定向 URI中放入您的 LangSmith 实例域名后跟/api/v1/oauth/custom-oidc/callback,例如https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback - 点击
创建,然后下载 JSON 或复制并保存Client ID(以.apps.googleusercontent.com结尾)和Client secret到安全的地方。如果需要,您稍后可以访问这些信息。 - 从左侧导航菜单中选择
OAuth consent screen- 选择应用程序类型为
Internal。如果选择Public,任何拥有 Google 帐户的人都可以登录。 - 输入描述性的
Application name。此名称在用户登录时显示在同意屏幕上。例如,使用LangSmith或<organization_name> SSO for LangSmith。 - 确认 Google API 的 Scopes 仅列出了 email、profile 和 openid 作用域。单点登录只需要这些作用域。如果您授予额外的作用域,会增加暴露敏感数据的风险。
- 选择应用程序类型为
- (可选)控制组织中谁有权访问 LangSmith:https://admin.google.com/ac/owl/list?tab=configuredApps。更多详情请参阅 Google 文档。
- 配置 LangSmith 以使用此 OAuth 应用程序。例如,以下是用于 Kubernetes 配置的
config值:oauthClientId:Client ID(以.apps.googleusercontent.com结尾)oauthClientSecret:Client secrethostname: 您的 LangSmith 实例的域名,例如https://langsmith.yourdomain.com(无尾随斜杠)oauthIssuerUrl:https://accounts.google.comoauth.enabled:trueauthType:mixed
Okta 身份提供商设置
支持的功能
- IdP 发起的 SSO
- SP 发起的 SSO
- 即时配置 (JIT)(参见 在 SSO 组织中管理用户访问)
配置步骤
更多信息,请参阅 Okta 的 文档。 如有任何问题或疑问,请通过 support.langchain.com 联系支持。通过 Okta 集成网络(推荐)
有关 SCIM 设置的详细信息,请参阅 为您的组织设置 SCIM。
要使用 SCIM 与 Okta,必须使用此配置方法。
- 登录 Okta。
- 在右上角,选择 Admin。该按钮在 Admin 区域不可见。
- 选择
浏览应用集成目录。 - 查找并选择 LangSmith 应用程序。
- 在应用程序概述页面上,选择添加集成。
- 填写
ApiUrlBase:- 您的 LangSmith API URL,不带协议 (
https://),格式为<langsmith_domain>/api/v1,例如langsmith.yourdomain.com/api/v1。 - 如果您的安装配置了子域 / 路径前缀,请将其包含在 URL 中,例如
langsmith.yourdomain.com/prefix/api/v1。
- 您的 LangSmith API URL,不带协议 (
- 将
AuthHost留空。 - (可选,如果计划同时使用 SCIM)填写
LangSmithUrl:上面的<langsmith_url>部分,例如langsmith.yourdomain.com。 - 在应用程序可见性下,保持复选框未选中。
- 选择下一步。
- 选择
OpenID Connect。 - 填写
登录选项:应用程序用户名格式:Email。更新应用程序用户名时机:创建和更新时。允许用户安全地查看其密码:保持未选中。
- 点击 保存。
- 配置 LangSmith 以使用此 OAuth 应用程序(有关
initialOrgAdminEmail的详细信息,请参阅 常规配置部分):
Helm
有关 SCIM 设置的详细信息,请参阅 为您的组织设置 SCIM。
通过自定义应用集成
- 以管理员身份登录 Okta,然后进入 Okta 管理控制台。
- 在 应用程序 > 应用程序 下,点击 创建应用集成。
- 选择 OIDC - OpenID Connect 作为登录方法,Web 应用程序 作为应用程序类型,然后点击 下一步。
- 输入
应用集成名称(例如LangSmith)。 - 建议:勾选 核心授权 > 刷新令牌(参见 会话长度控制)。
- 在 登录重定向 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。 - 在 登出重定向 URI 下,将值设置为您的 LangSmith URL,例如
https://langsmith.yourdomain.com。这确保当用户登出 LangSmith 时,IdP 会话将被终止。 - 在 受信任的来源 > 基础 URI 下,添加您的 LangSmith URL(带协议),例如
https://langsmith.yourdomain.com。 - 在 分配 > 受控访问 下选择您想要的选项:
- 允许组织中的每个人访问。
- 限制对选定组的访问。
- 现在跳过组分配。
- 点击 保存。
- 在 登录 > OpenID Connect ID 令牌 下,将 颁发者 设置为 Okta URL。
- (可选)在 常规 > 登录 下,将 登录发起方 设置为
Okta 或应用均可以,以启用 IdP 发起的登录。 - (建议)在 常规 > 登录 > 电子邮件验证体验 下,在 回调 URI 中填写 LangSmith URL,例如
https://langsmith.yourdomain.com。 - 配置 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:
oid 声明:
SSO 组同步
自托管版的 SSO 组同步需要 LangSmith 图表版本 0.15.0-rc.3(应用程序版本 0.15.2rc1)或更高版本。
- 配置您的 IdP 应用程序在 OIDC ID 令牌中发出组成员声明。源属性和生成的声明名称因 IdP 而异。常见示例包括
groups、roles或自定义声明名称。LangSmith 不限定源属性。 - 根据您的 IdP,您可能需要将额外的作用域(通常是
groups)添加到oauthScopes以接收该声明。请查阅您的 IdP 文档以了解所需的作用域以及将组成员包含在令牌中所需的任何其他配置。 - 组名称必须遵循 SCIM 命名约定(例如
LS:Organization Admin、LS:Organization User:prod:Editor)。分隔符与 SCIM 通过scim_group_name_separator共享。
groups),请将其添加到 oauthScopes:
Helm
groups、roles 等)取决于您的 IdP。请查阅您的 IdP 的 OIDC 文档。
LangSmith 侧配置:
每个提供者的 SSO 组同步设置存储在 SSO 提供者记录上,并通过 LangSmith UI 或 API 切换(不通过 Helm 值)。
- UI
- API
一旦您的 IdP 发出组声明,可以从 UI 在 设置 → 成员和角色 → SSO 配置 → SSO 组同步 中配置 SSO 组同步。在 Groups claim field 中配置的声明名称必须与您的 IdP 发出的声明匹配。
从 Microsoft Entra ID 发出组声明
对于自托管版的 OIDC,请通过应用注册清单添加组声明。跳过 令牌配置 > 添加组声明 流程,该流程不支持仅云安全组的显示名称。 在 应用注册 > 您的应用 > 清单 中,将以下内容合并到清单中,保留任何现有的optionalClaims.idToken 条目,例如 email:
为 SSO 组同步创建 Microsoft Entra ID 组
用于 SSO 组同步的组必须遵循主用户管理页面上记录的 组命名约定(例如LS:Organization Admins、LS:Organization User:Production:Editor)。组名称区分大小写,并且必须完全匹配该约定。
要在 Microsoft Entra ID 中创建组:
- 在 Microsoft Entra 管理中心,转到 组 > 新建组。
- 将 组类型 设置为
Security。 - 将 成员身份类型 设置为
Assigned(不支持动态成员身份)。 - 将 组名 设置为符合命名约定的值。
- 添加成员,然后点击 创建。
验证令牌中的组声明
完成 IdP 侧配置后,验证 OIDC ID 令牌是否包含预期的组声明:- 从 LangSmith 登出,然后通过 SSO 重新登录。
- 在浏览器的开发者工具中,转到 Application > Cookies,找到 OAuth 会话 cookie。
- 使用 JWT 解码器(例如 jwt.io)解码 ID 令牌,并确认
groups声明包含显示名称,而不是对象 ID:
groupMembershipClaims 值,并确认组已在 用户和组 下分配给企业应用程序。
PKCE 流程(已弃用)
我们建议使用客户端密钥 运行。但是,如果您的身份提供商不支持此方式,您可以使用 带 PKCE 的授权码 流程。
要求
此流程不需要
客户端密钥。- 您的身份提供商必须支持
带 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
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

