用 OAuth2.0 和 OIDC 设置 SSO

LangSmith Self-Hosted 通过 OAuth2.0 和 OIDC 提供 SSO，它把身份验证委派给你的身份提供商（IdP）来管理对 LangSmith 的访问。

LangSmith 的实现支持任何 OIDC 合规的提供商。一旦配置好，你会看到一个提示 Log in via SSO 的登录页。

默认情况下，LangSmith Self-Hosted 支持带 Client Secret 的 Authorization Code 流程。在这个流程版本中，你的 client secret 被安全地存在 LangSmith（而非前端）中，用于身份验证和建立会话。

注意事项

你可以把一个 basic auth 安装升级到 oauth 模式，但不能升级一个 none auth 安装。
- 通过移除 basic auth 配置参数并添加带 client secret 的 OAuth 配置参数来升级一个 basic auth 安装。此后用户只能通过 OAuth 登录。要在升级后保持访问，你必须能用一个之前通过 basic auth 登录过的邮箱地址登录 OAuth。
LangSmith 不支持：
- 在自托管中从 SSO 迁到 basic auth 模式。
- 从带 client secret 的 OAuth 模式迁到不带 client secret 的 OAuth 模式，反之亦然。
- 同时拥有 basic auth 和 OAuth。启用 OAuth 时确保你禁用 basic auth 配置。

前置条件

你必须具备以下内容才能完成提供商设置：

处于自托管且在 Enterprise 方案上。
一个支持带 Client Secret 的 Authorization Code 流程的 IdP。
一个支持使用外部 discovery/issuer URL 的 IdP。LangSmith 用它来获取你 IdP 所需的路由和密钥。
OIDC、email 和 profile 作用域。LangSmith 用它们来获取所需用户信息和用户邮箱。

NOTE

LangSmith SSO 只支持通过 https。

配置

你需要在 IdP 中把回调 URL 设为 https://<host>/api/v1/oauth/custom-oidc/callback，其中 host 是你为 LangSmith 实例预配的域名或 IP。这是你 IdP 在用户身份验证后将重定向他们的地方。
要在登录时终止 IdP 会话（迫使用户重新身份验证），把你LangSmith URL（例如 https://<host>）在 IdP 中注册为一个 post-logout redirect URI（有时叫 Sign-out redirect URI），然后通过 Helm 中的 commonEnv 在你的环境里设 OAUTH_IDP_LOGOUT_ENABLED=true。
你需要在 values.yaml 文件中提供 oauthClientId、oauthClientSecret、hostname 和 oauthIssuerUrl。这是你配置 LangSmith 实例的地方。
如果你尚未配置带 client secret 的 OAuth，或你只有个人组织，你必须提供一个邮箱地址作为新预配 SSO 组织的 initialOrgAdminEmail。如果你从basic auth升级，LangSmith 会复用你现有的组织。

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com
  initialOrgAdminEmail: test@email.com # Set this if required
  oauth:
    enabled: true
    oauthClientId: <YOUR CLIENT ID>
    oauthClientSecret: <YOUR CLIENT SECRET>
    oauthIssuerUrl: <YOUR DISCOVERY URL>
    oauthScopes: "email,profile,openid"

提供商设置

Microsoft Entra ID IdP 设置

用 OAuth2.0 和 OIDC 将 Microsoft Entra ID 配置为单点登录提供商。更多信息，参阅 Microsoft 的 OpenID Connect 文档。

NOTE

在 Microsoft Entra ID 中注册应用需要你在租户中的 Application Administrator 或 Cloud Application Administrator 角色或更高。

步骤 1. 注册应用

在 Microsoft Entra admin center 中，前往 Applications > App registrations > New registration。
把 Name 设为一个能识别应用的值，例如 LangSmith Self-Hosted。
把 Supported account types 设为 Accounts in this organizational directory only (Single tenant)。
在 Redirect URI 下，选择 Web 作为平台并输入 https://<host>/api/v1/oauth/custom-oidc/callback，其中 <host> 是你 LangSmith 实例的域名。
点击 Register。

从应用的 Overview 页面，记录以下值用于 Helm 配置：

Application (client) ID：用作 oauthClientId。
Directory (tenant) ID：用于构造 issuer URL。
OIDC issuer URL：https://login.microsoftonline.com/<tenant-id>/v2.0，用作 oauthIssuerUrl。

步骤 2. 创建一个 client secret

在应用注册中，前往 Certificates & secrets > Client secrets > New client secret。
输入一个描述，选一个过期时间，然后点击 Add。
立即复制该 secret 的 Value。Microsoft Entra ID 在你离开页面后会隐藏这个值。用它作为 oauthClientSecret。

在配置 Helm 之前，把 Client ID、Client Secret 和 Issuer URL 存在你的机密存储中。

步骤 3. 添加 email 可选声明

没有这一步，LangSmith 会用错误 Your identity provider did not provide an email address 阻止登录。

在应用注册中，前往 Token configuration > Add optional claim。
选择 ID 作为令牌类型。
勾选 email，然后点击 Add。
被提示时，接受授予 Microsoft Graph email 权限的请求。

步骤 4. 配置 LangSmith

把前面步骤的值应用到你的 Helm 配置：

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com
  initialOrgAdminEmail: test@email.com # Set this if required
  oauth:
    enabled: true
    oauthClientId: "<APPLICATION (CLIENT) ID>"
    oauthClientSecret: "<CLIENT SECRET VALUE>"
    oauthIssuerUrl: "https://login.microsoftonline.com/<TENANT ID>/v2.0"
    oauthScopes: "email,profile,openid"

有关 initialOrgAdminEmail 的详情，参阅通用配置一节。

NOTE

Microsoft Entra ID 的 oid 声明默认被用作 OIDC 的 sub 声明。详情参阅覆盖 sub 声明。

要在登录时从 Microsoft Entra ID 群组指派组织和工作区角色，参阅 SSO Groups Sync。

Google workspace IdP 设置

你可以用 OAuth2.0 和 OIDC 不带 PKCE 地将 Google Workspace 用作单点登录（SSO）提供商。

NOTE

你必须有组织 Google Cloud Platform（GCP）账户的管理员级访问权来创建一个新项目，或有一个现有项目上创建和配置 OAuth 2.0 凭据的权限。我们建议创建一个新项目来管理访问，因为每个 GCP 项目只有一个 OAuth 同意屏。

创建一个新的 GCP 项目，见 Google 文档主题创建和管理项目
创建项目后，在 Google API Console 中打开 Credentials 页面（确保左上角的项目正确）
创建新凭据：Create Credentials > OAuth client ID
选择 Web application 作为 Application type，并为应用输入一个名字，例如 LangSmith
在 Authorized Javascript origins 中放入你 LangSmith 实例的域名，例如 https://langsmith.yourdomain.com
在 Authorized redirect URIs 中放入你 LangSmith 实例的域名后面跟 /api/v1/oauth/custom-oidc/callback，例如 https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback
点击 Create，然后下载 JSON 或复制并安全保存 Client ID（以 .apps.googleusercontent.com 结尾）和 Client secret。如需要，你以后仍能访问这些。
从左侧导航菜单选择 OAuth consent screen
1. 选择应用类型为 Internal。如果你选 Public，任何有 Google 账户的人都能登录。
2. 输入一个描述性的 Application name。这个名字在用户登录时展示在同意屏上。例如，用 LangSmith 或 <organization_name> SSO for LangSmith。
3. 核实 Scopes for Google APIs 只列出 email、profile 和 openid 作用域。单点登录只需要这些作用域。如果你授予额外作用域，会增加暴露敏感数据的风险。
（可选）控制你组织内谁有权访问 LangSmith：https://admin.google.com/ac/owl/list?tab=configuredApps。更多详情见 Google 文档。
配置 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 IdP 设置

受支持的功能

IdP 发起的 SSO
SP 发起的 SSO
即时（Just-In-Time）预配（见管理 SSO 组织中的用户访问）

配置步骤

更多信息，见 Okta 的文档。如有任何疑问或问题，请通过 support.langchain.com 联系支持。

经由 Okta 集成网络（推荐）

INFO

有关 SCIM 设置的详情，参阅为你的组织设置 SCIM。

NOTE

要与 Okta 一起使用 SCIM，必须用这种配置方法。

登录 Okta。
在右上角，选择 Admin。这个按钮在 Admin 区域不可见。
选择 Browse App Integration Catalog。
找到并选择 LangSmith 应用。
在应用概览页，选择 Add Integration。
填写 ApiUrlBase：
- 你的 LangSmith API URL，不带协议（https://），格式为 <langsmith_domain>/api/v1，例如 langsmith.yourdomain.com/api/v1。
- 如果你的安装配了一个子域/路径前缀，把它包含在 URL 中，例如 langsmith.yourdomain.com/prefix/api/v1。
把 AuthHost 留空。
（可选，若计划同时使用 SCIM）填写 LangSmithUrl：上面那部分的 <langsmith_url>，例如 langsmith.yourdomain.com。
在 Application Visibility 下，保持该框未勾选。
选择 Next。
选择 OpenID Connect。
填写 Sign-On Options：
- Application username format：Email。
- Update application username on：Create and update。
- Allow users to securely see their password：保持未勾选。
点击 Save。
配置 LangSmith 使用这个 OAuth 应用（有关 initialOrgAdminEmail 的详情见通用配置一节）：

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com # the domain of your instance (note no trailing slash)
  initialOrgAdminEmail: test@email.com # Set this if required
  oauth:
    enabled: true
    oauthClientId: "Client ID" # (starts with `0o`)
    oauthClientSecret: "Client secret"
    oauthIssuerUrl: "https://company-7422949.okta.com" # the URL of your Okta instance
    oauthScopes: "email,profile,openid"

INFO

有关 SCIM 设置的详情，参阅为你的组织设置 SCIM。

经由自定义应用集成

WARNING

SCIM 不兼容这种配置方法。参阅 经由 Okta 集成网络。

以管理员登录 Okta，前往 Okta Admin console。
在 Applications > Applications 下点击 Create App Integration。
选择 OIDC - OpenID Connect 作为 Sign-in 方法，Web Application 作为应用类型，然后点击 Next。
输入一个 App integration name（例如 LangSmith）。
推荐：勾选 Core grants > Refresh Token（见会话长度控件）。
在 Sign-in redirect URIs 中放入你 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。
在 Sign-out redirect URIs 下，把值设为你的 LangSmith URL，例如 https://langsmith.yourdomain.com。这确保在用户登出 LangSmith 时 IdP 会话被终止。
在 Trusted Origins > Base URIs 下，添加带协议的你的 langsmith URL，例如 https://langsmith.yourdomain.com。
在 Assignments > Controlled access 下选择你想要的选项：
- 允许组内所有人访问。
- 限制访问到选定的群组。
- 暂跳过群组指派。
点击 Save。
在 Sign On > OpenID Connect ID Token 下，把 Issuer 设为 Okta URL。
（可选）在 General > Login 下把 Login initiated by 设为 Either Okta or App 以启用 IdP 发起的登录。
（推荐）在 General > Login > Email verification experience 下，把 Callback URI 填为 LangSmith URL，例如 https://langsmith.yourdomain.com。
配置 LangSmith 使用这个 OAuth 应用（有关 initialOrgAdminEmail 的详情见通用配置一节）：

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com # the domain of your instance (note no trailing slash)
  initialOrgAdminEmail: test@email.com # Set this if required
  oauth:
    enabled: true
    oauthClientId: "Client ID" # (starts with `0o`)
    oauthClientSecret: "Client secret"
    oauthIssuerUrl: "https://company-7422949.okta.com" # the URL of your Okta instance
    oauthScopes: "email,profile,openid"

SP 发起的 SSO

用户可以用 LangSmith 首页上的 Login via SSO 按钮登录。

高级选项

会话长度控件

NOTE

本节中所有环境变量都用于 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 错误拒绝登录。如果你的 IdP 因此拒绝多作用域登录，在 Helm 中设 urlEncodeScopeSpaces: true，以把空格编码为 %20 取而代之，这是所有 OIDC 合规提供商接受的编码。这只适用于带 OAuth client secret 的 authType: mixed，默认关。

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com
  oauth:
    enabled: true
    oauthClientId: <YOUR CLIENT ID>
    oauthClientSecret: <YOUR CLIENT SECRET>
    oauthIssuerUrl: <YOUR DISCOVERY URL>
    oauthScopes: "email,profile,openid"
    urlEncodeScopeSpaces: true

覆盖 sub 声明

在某些场景下，可能需要覆盖你身份提供商中哪个声明被用作 sub 声明。例如，在 SCIM 中，解析出的 sub 声明和 SCIM externalId 必须匹配，登录才能成功。如果 sub 声明的来源属性和/或 SCIM externalId 有限制，设 ISSUER_SUB_CLAIM_OVERRIDES 环境变量来选择哪个 OIDC JWT 声明被用作 sub。

如果一个 issuer URL 以本配置中的某个 URL 开头，sub 声明取自所指定的字段名。例如，用以下配置，一个带 issuer https://idp.yourdomain.com/application/uuid 的令牌会用 customClaim 值作为 sub：

ISSUER_SUB_CLAIM_OVERRIDES='{"https://idp.yourdomain.com": "customClaim"}'

如果未设，本配置的默认值在 Azure Entra ID 被用作身份提供商时使用 oid 声明：

ISSUER_SUB_CLAIM_OVERRIDES='{"https://login.microsoftonline.com/": "oid", "https://sts.windows.net/": "oid", "https://login.microsoftonline.us/": "oid", "https://login.partner.microsoftonline.cn/": "oid"}'

SSO 组同步

NOTE

自托管上的 SSO 组同步需要 LangSmith chart 版本 0.15.0-rc.3（应用版本 0.15.2rc1）或更高。

SSO Groups Sync 让 LangSmith 从 OIDC 令牌上的一个群组成员声明指派组织和工作区角色，作为 SCIM 的一个更简单替代。在自托管上，你必须先配置 IdP 在 OIDC ID 令牌中包含群组，LangSmith 才能读它们。

IdP 端配置（因提供商而异）：

配置你的 IdP 应用在 OIDC ID 令牌中发出一个群组成员声明。来源属性和结果声明名因 IdP 而异。常见的例子包括 groups、roles，或一个自定义声明名。LangSmith 不规定来源属性。
根据你的 IdP，你可能需要向 oauthScopes 添加一个额外作用域（常见为 groups）以收到该声明。查阅你 IdP 的文档，了解所需作用域以及在令牌中包含群组成员所需的任何额外配置。
群组名必须遵循 SCIM 命名约定（例如 LS:Organization Admin、LS:Organization User:prod:Editor）。分隔符通过 scim_group_name_separator 与 SCIM 共享。

Helm 配置：

如果你的 IdP 需要一个额外的 OIDC 作用域在令牌中包含群组（常见为 groups），把它添加到 oauthScopes：

yaml

config:
  authType: mixed
  hostname: https://langsmith.example.com
  oauth:
    enabled: true
    oauthClientId: <YOUR CLIENT ID>
    oauthClientSecret: <YOUR CLIENT SECRET>
    oauthIssuerUrl: <YOUR DISCOVERY URL>
    oauthScopes: "email,profile,openid,groups"

确切的作用域名（groups、roles 等）取决于你的 IdP。查阅你 IdP 的 OIDC 文档。

LangSmith 端配置：

按提供商的 SSO Groups Sync 设置存在 SSO 提供商记录上，并通过 LangSmith UI 或 API 切换（不是通过 Helm 值）。

一旦你的 IdP 发出 groups 声明，就能从 UI 在 Settings > Members and roles > SSO Configuration > SSO Groups Sync 配置 SSO Groups Sync。在 Groups claim field 中配置的声明名必须与你 IdP 发出的声明匹配。

从 Microsoft Entra ID 发出 groups 声明

对于自托管上的 OIDC，通过应用注册清单添加 groups 声明。跳过 Token configuration > Add groups claim 流程，它不支持云专属安全群的显示名。

WARNING

把顶层 groupMembershipClaims 属性设为 "ApplicationGroup"。其他值会以一种难以诊断的方式改变行为：

缺失或 "None"：令牌中不出现任何群组。
"SecurityGroup" 或 "All"：群组会出现，但 cloud_displayname 值被静默忽略，令牌包含的是群组对象 ID 而非名字。
"ApplicationGroup"：群组解析为显示名，但仅对在 Users and groups 下明确指派给企业应用的群组。

cloud_displayname 值只对企业应用支持。

在 App registrations > 你的应用 > Manifest 中，把以下内容合并进清单，保留任何现有的 optionalClaims.idToken 条目（如 email）：

json

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
  "idToken": [
    {
      "name": "email",
      "source": null,
      "essential": false,
      "additionalProperties": []
    },
    {
      "name": "groups",
      "source": null,
      "essential": false,
      "additionalProperties": ["cloud_displayname"]
    }
  ],
  "accessToken": [],
  "saml2Token": []
}

然后，在 Enterprise applications > 你的应用 > Users and groups 中，指派每个映射到一个 LangSmith 角色的群组。未指派给企业应用的群组不会出现在令牌中。

为 SSO Groups Sync 创建 Microsoft Entra ID 群组

用于 SSO Groups Sync 的群组必须遵循记录在主用户管理页上的群组命名约定（例如 LS:Organization Admins、LS:Organization User:Production:Editor）。群组名区分大小写且必须精确匹配约定。

要在 Microsoft Entra ID 中创建一个群组：

在 Microsoft Entra admin center 中，前往 Groups > New group。
把 Group type 设为 Security。
把 Membership type 设为 Assigned（不支持动态成员）。
把 Group name 设为一个匹配命名约定的值。
添加成员，然后点击 Create。

群组成员变更在每个用户的下次登录时生效。

验证令牌中的 groups 声明

完成 IdP 端配置后，验证 OIDC ID 令牌包含预期的 groups 声明：

登出 LangSmith，然后通过 SSO 重新登录。
在浏览器的开发者工具中，前往 Application > Cookies 并找到 OAuth 会话 cookie。
用一个 JWT 解码器（例如 jwt.io）解码 ID 令牌，并确认 groups 声明包含的是显示名而非对象 ID：

json

{
  "groups": [
    "LS:Organization Admins",
    "LS:Organization User:Production:Editor"
  ]
}

如果声明包含的是 UUID 而非名字，重新查看清单中的 groupMembershipClaims 值，并确认群组已在 Users and groups 下指派给了企业应用。

PKCE 流程（已弃用）

我们建议带一个 Client Secret 运行。不过，如果你的 IdP 不支持这一点，你可以使用 Authorization Code with PKCE 流程。

WARNING

PKCE 工作流自 v16 起已弃用，并将在 v17 中完全移除。会提供一条从 PKCE 到带 client secret OAuth 的迁移路径。我们建议尽快迁移到client secret 流程。

要求

NOTE

这个流程不要求 Client Secret。

用 LangSmith 使用 OAuth SSO 有几项要求：

你的 IdP 必须支持 Authorization Code with PKCE 流程（例如 Google 不支持这个流程，但见上方一个 Google 支持的替代配置）。这常在提供商里显示为配置一个"Single Page Application (SPA)"
你的 IdP 必须支持使用外部 discovery/issuer URL。我们用它来获取你 IdP 所需的路由和密钥。
你必须向 LangSmith 提供 OIDC、email 和 profile 作用域。我们用它们来获取所需用户信息和用户邮箱。
你需要在 IdP 中把回调 URL 设为 http://<host>/oauth-callback，其中 host 是你为 LangSmith 实例预配的域名或 IP。这是你 IdP 在用户身份验证后将重定向他们的地方。
你需要在 values.yaml 文件中提供 oauthClientId 和 oauthIssuerUrl。这是你配置 LangSmith 实例的地方。

yaml

config:
  oauth:
    enabled: true
    oauthClientId: <YOUR CLIENT ID>
    oauthIssuerUrl: <YOUR DISCOVERY URL>

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织