以编程方式使用文档

LangSmith 自托管版本通过 OAuth2.0 和 OIDC 提供 SSO。这将把身份验证委托给您的身份提供商 (IdP) 来管理对 LangSmith 的访问。

我们的实现支持几乎所有符合 OIDC 标准的功能，只有少数例外。配置完成后，您将看到如下登录界面：

!带有 OAuth SSO 的 LangSmith 界面

概述

使用客户端密钥（推荐）

默认情况下，LangSmith 自托管版本支持 Authorization Code 流程 Client Secret在此流程版本中，您的客户端密钥安全存储在 LangSmith（而非前端），用于身份验证和建立认证会话。

前提条件

  • * 您必须是自托管用户且使用企业版计划。
  • * 您的 IdP 必须支持 Authorization Code 流程 Client Secret.
  • * Your IdP must support using an external discovery/issuer URL. We will use this to fetch the necessary routes and keys for your IdP.
  • * 您必须提供 OIDC, email和 profile 作用域给 LangSmith。我们使用这些来获取您用户的必要用户信息和电子邮件。

配置

  • * 您需要在 IdP 中设置回调 URL 为 https://<host>/api/v1/oauth/custom-oidc/callback，其中 host 是您为 LangSmith 实例配置的域名或 IP。这是您的 IdP 在用户完成身份验证后将用户重定向到的地址。
  • * 为了在注销时终止 IdP 会话（使用户必须重新进行身份验证），请在您的 IdP 中注册您的 LangSmith URL（例如： https://<host>) as a **注销后重定向 URI** （有时称为"退出重定向 URI"） OAUTH_IDP_LOGOUT_ENABLED=true ，然后在您的环境中设置 commonEnv 通过 Helm 或您的 .env 文件（在 Docker Compose 中）。
  • * 您需要提供 oauthClientId, oauthClientSecret, hostname和 oauthIssuerUrl 在您的 values.yaml 文件中。这是您配置 LangSmith 实例的位置。
  • * 如果您 **尚未** 配置带客户端密钥的 OAuth，或者您只有个人组织，您必须提供一个电子邮件地址来指定为新配置 SSO 组织的初始组织管理员。如果您从基本认证升级，现有的组织将被重用。
config:
  authType: mixed
  hostname: https://langsmith.example.com
  initialOrgAdminEmail: test@email.com # Set this if required
  oauth:
    enabled: true
    oauthClientId:
    oauthClientSecret:
    oauthIssuerUrl:
    oauthScopes: "email,profile,openid"
# In your .env file
AUTH_TYPE=mixed
INITIAL_ORG_ADMIN_EMAIL=test@email.com
LANGSMITH_URL=https://langsmith.example.com
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER_URL=https://your-issuer-url
OAUTH_SCOPES=email,profile,openid

会话时长控制

  • * 默认情况下，会话时长由身份提供商返回的身份令牌的过期时间控制
  • * 大多数配置应使用刷新令牌，以便在身份令牌过期后将会话时长延长至 OAUTH_SESSION_MAX_SEC，这可能需要在 offline_access 中添加 oauthScopes 作用域（Helm）或 OAUTH_SCOPES （Docker）
  • * OAUTH_SESSION_MAX_SEC （默认 1 天）可被覆盖，最多一周（604800)
  • * 对于不支持刷新令牌的身份提供商配置，设置 OAUTH_OVERRIDE_TOKEN_EXPIRY="true" 将使 OAUTH_SESSION_MAX_SEC 作为会话时长，忽略身份令牌过期时间

覆盖子声明

在某些场景下，可能需要覆盖使用哪个声明作为 sub 声明（来自您的身份提供商）。 例如，在 SCIM 中，已解析的 sub 声明和 SCIM externalId 必须匹配，登录才能成功。 如果对 sub claim and/or the SCIM externalId的源属性有限制，请设置 ISSUER_SUB_CLAIM_OVERRIDES 环境变量来选择使用哪个 OIDC JWT 声明作为 sub.

如果签发者 URL **以以下任一 URL 开头** ，则 sub 声明从指定的字段名中获取。 例如，使用以下配置，具有以下签发者的令牌 https://idp.yourdomain.com/application/uuid 将使用 customClaim 值作为 sub:

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

如果未设置，此配置的默认值为 oid 声明，当使用 Azure Entra ID 作为身份提供者时：

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 群组同步

SSO 群组同步 允许 LangSmith 从 OIDC 令牌中的群组成员资格声明分配组织和项目角色，作为以下项的更简单替代方案 SCIM。在自托管上，必须先配置 IdP 将群组包含在 OIDC ID 令牌中，然后 LangSmith 才能读取它们。

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

  1. 配置 IdP 应用程序以在 OIDC ID 令牌中发出群组成员资格声明。源属性和生成的声明名称因 IdP 而异。常见示例包括 groups, roles，或自定义声明名称。LangSmith 不规定源属性。
  2. 根据 IdP 的不同，可能需要添加额外的范围（通常是 groups) to oauthScopes ）来接收声明。请查阅 IdP 的文档以了解所需范围以及在令牌中包含群组成员资格所需的任何额外配置。
  3. 群组名称必须遵循 SCIM 命名约定 (e.g., LS:Organization Admin, LS:Organization User:prod:Editor）。分隔符与 SCIM 共享 scim_group_name_separator.

Helm 配置：

如果您的 IdP 需要额外的 OIDC 范围来在令牌中包含组（通常 groups），请将其添加到 oauthScopes:

config:
  authType: mixed
  hostname: https://langsmith.example.com
  oauth:
    enabled: true
    oauthClientId:
    oauthClientSecret:
    oauthIssuerUrl:
    oauthScopes: "email,profile,openid,groups"
# In your .env file
AUTH_TYPE=mixed
LANGSMITH_URL=https://langsmith.example.com
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER_URL=https://your-issuer-url
OAUTH_SCOPES=email,profile,openid,groups

确切的范围名称（groups, roles等）取决于您的 IdP。请查阅您 IdP 的 OIDC 文档。

LangSmith 端配置：

每个提供商的 SSO 群组同步设置存储在 SSO 提供商记录中，并通过 LangSmith UI or API 切换（不是通过 Helm 值）。一旦您的 IdP 发出组声明，请从 UI 中的以下位置配置 SSO 群组同步 **设置** → **成员和角色** → **SSO 配置** → **SSO 群组同步**。或者，通过 API 进行配置，如 主 SSO 群组同步文档中所述。在 **组声明字段** 中配置的声明名称必须与您 IdP 发出的声明匹配。

Google Workspace IdP 设置

您可以使用 Google Workspace 作为单点登录 (SSO) 提供商，使用 OAuth2.0 和 OIDC 无 PKCE。

  1. 创建新的 GCP 项目，请参阅 Google 文档主题 创建和管理项目
  1. 创建项目后，打开 凭证 Google API Console 中的页面（确保左上角的项目正确）
  1. 创建新凭证： Create Credentials → OAuth client ID
  1. 选择 Web application 作为 Application type 并输入应用程序名称，例如 LangSmith
  1. In Authorized Javascript origins 输入您的 LangSmith 实例的域名，例如 https://langsmith.yourdomain.com
  1. In Authorized redirect URIs 输入您的 LangSmith 实例的域名，后跟 /api/v1/oauth/custom-oidc/callback e.g. https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback
  1. 点击 Create，然后下载 JSON 或复制并保存 Client ID （以 .apps.googleusercontent.com结尾）和 Client secret 到安全的地方。 **如果需要，您稍后可以访问这些**.
  1. 从左侧导航菜单中选择 OAuth consent screen 从左侧导航菜单中
  1. 选择应用程序类型为 Internal. **如果您选择 Public，任何拥有 Google 账户的人都可以登录。**
  2. 输入描述性 Application name。此名称会在用户登录时显示在同意屏幕上。例如，使用 LangSmith or <organization_name> SSO for LangSmith.
  3. 验证 Google API 的作用域仅列出 email、profile 和 openid 作用域。单一登录仅需要这些作用域。如果授予额外作用域，会增加暴露敏感数据的风险。
  1. （可选）控制组织内谁可以访问 LangSmith： https://admin.google.com/ac/owl/list?tab=configuredApps。请参阅 Google 文档 了解更多详情。
  1. 配置 LangSmith 使用此 OAuth 应用程序。例如，以下是 config用于 Kubernetes 配置的值：
  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 集成网络（推荐）

1. 登录 Okta. 1. 在右上角选择 Admin。从管理员区域无法看到此按钮。 1. 选择 Browse App Integration Catalog. 1. 找到并选择 LangSmith 应用程序。 1. 在应用程序概览页面，选择添加集成。 1. 填写 ApiUrlBase: * 您的 LangSmith API URL **不带协议** (https://）格式为 <langsmith_domain>/api/v1, e.g., langsmith.yourdomain.com/api/v1. * If your installation is configured with a subdomain / path prefix, include that in the URL, e.g., langsmith.yourdomain.com/prefix/api/v1. 1. 保留 AuthHost empty. 1. （可选，如果您计划同时使用 SCIM 也适用）填写 LangSmithUrl：上述 <langsmith_url> 部分，例如 langsmith.yourdomain.com. 1. 在应用程序可见性下，保持复选框未选中。 1. 选择下一步。 1. 选择 OpenID Connect. 1. 填写 Sign-On Options: * Application username format: Email. * Update application username on: Create and update. * Allow users to securely see their password：保留 **未选中**. 1. 点击 **保存**. 1. 配置 LangSmith 使用此 OAuth 应用程序（请参阅 通用配置部分 了解详细信息 initialOrgAdminEmail):

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"
# In your .env file
AUTH_TYPE=mixed
INITIAL_ORG_ADMIN_EMAIL=test@email.com # Set this if required
LANGSMITH_URL=https://langsmith.example.com # the domain of your instance (note no trailing slash)
OAUTH_CLIENT_ID="Client ID" # (starts with `0o`)
OAUTH_CLIENT_SECRET="Client secret"
OAUTH_ISSUER_URL="https://company-7422949.okta.com" # the URL of your Okta instance
OAUTH_SCOPES=email,profile,openid
通过自定义应用集成

1. 以管理员身份登录 Okta，然后进入 **Okta 管理控制台**. 1. 在 **应用程序** > **应用程序** 点击 **创建应用集成**. 1. 选择 **OIDC - OpenID Connect** 作为登录方式，并 **Web 应用程序** 作为应用程序类型，然后点击 **下一步**. 1. 输入 App integration name (e.g., LangSmith). 1. 建议：勾选 **核心授权 > 刷新令牌** （参见 会话时长控制). 1. In **登录重定向 URI** 输入您的 LangSmith 实例域名，后跟 /api/v1/oauth/custom-oidc/callback, e.g., https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback. If your installation is configured with a subdomain / path prefix, include that in the URL, e.g., https://langsmith.yourdomain.com/prefix/api/v1/oauth/custom-oidc/callback. 1. 在 **登出重定向 URI**，将值设置为您的 LangSmith URL，例如 https://langsmith.yourdomain.com。这确保当用户从 LangSmith 注销时，IdP 会话被终止。 1. 在 **可信来源 > 基础 URI** 添加带协议的 langsmith URL，例如 https://langsmith.yourdomain.com. 1. 在 **分配 > 受控访问**: * 允许组织中的每个人访问。 * 限制对选定组的访问。 * 暂时跳过组分配。 1. 点击 **保存**. 1. 在 **登录 > OpenID Connect ID 令牌** 设置 **颁发者** to **Okta URL**. 1. （可选）在 **常规 > 登录** 设置 **登录发起方** to Either Okta or App 以启用 IdP 发起登录。 1. （建议）在 **常规 > 登录 > 电子邮件验证体验** 填写 **回调 URI** ，使用 LangSmith URL，例如 https://langsmith.yourdomain.com. 1. 配置 LangSmith 使用此 OAuth 应用程序（参见 常规配置部分 了解有关 initialOrgAdminEmail):

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"
# In your .env file
AUTH_TYPE=mixed
INITIAL_ORG_ADMIN_EMAIL=test@email.com # Set this if required
LANGSMITH_URL=https://langsmith.example.com # the domain of your instance (note no trailing slash)
OAUTH_CLIENT_ID="Client ID" # (starts with `0o`)
OAUTH_CLIENT_SECRET="Client secret"
OAUTH_ISSUER_URL="https://company-7422949.okta.com" # the URL of your Okta instance
OAUTH_SCOPES=email,profile,openid

SP 发起 SSO

用户可以使用 **通过 SSO 登录** 按钮登录 LangSmith。

无客户端密钥 (PKCE)（已弃用）

我们建议使用 Client Secret （如果可能的话）（之前我们不支持此功能）。但是，如果您的 IdP 不支持此功能，您可以使用 Authorization Code with PKCE flow.

此流程 *不* 需要 Client Secret。如需替代工作流程，请参阅 使用客户端密钥.

要求

使用 LangSmith 的 OAuth SSO 有几个要求：

  • * 您的 IdP 必须支持 Authorization Code with PKCE 流程 （例如，Google 不支持此流程，但请参阅 上文 中 Google 支持的替代配置）。这通常在您的 OAuth Provider 中显示为配置"单页应用程序 (SPA)"
  • * Your IdP must support using an external discovery/issuer URL. We will use this to fetch the necessary routes and keys for your IdP.
  • * 您必须向 LangSmith 提供 OIDC, email和 profile 作用域。我们使用这些来获取您用户所需的用户信息和电子邮件。
  • * 您需要在 IdP 中将回调 URL 设置为 http://<host>/oauth-callback，其中 host 是您为 LangSmith 实例配置的域名或 IP。这是您的 IdP 在用户完成身份验证后将用户重定向到的位置。
  • * 您需要提供 oauthClientId 和 oauthIssuerUrl 在您的 values.yaml 文件中。这是您配置 LangSmith 实例的位置。
config:
  oauth:
    enabled: true
    oauthClientId:
    oauthIssuerUrl: 
# In your .env file
AUTH_TYPE=oauth
OAUTH_CLIENT_ID=your-client-id
OAUTH_ISSUER_URL=https://your-issuer-url