使用 OAuth2.0 和 OIDC 进行 SSO

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

我们的实现几乎支持任何符合 OIDC 规范的内容，但有少数例外。配置后，您将看到如下登录屏幕：

带客户端密钥（推荐）

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

要求

注意

您可以将基本身份验证安装升级到此模式，但不能升级无身份验证安装。要升级，只需移除基本身份验证配置并添加所需的配置参数，如下所示。然后，用户只能通过 OAuth 登录。为了在升级后保持访问权限，您必须能够通过 OAuth 使用之前通过基本身份验证登录的电子邮件地址进行登录。

警告

LangSmith 目前不支持在自托管中从 SSO 模式切换到基本身份验证模式。我们也不支持带客户端密钥的 OAuth 模式与不带客户端密钥的 OAuth 模式之间的相互切换。最后，我们不支持同时启用基本身份验证和 OAuth。启用 OAuth 时请务必禁用基本身份验证配置。

• 您的 IdP 必须支持带客户端密钥的授权码流程。
• 您的 IdP 必须支持使用外部发现/颁发者 URL。我们将使用它来获取您的 IdP 所需的路由和密钥。
• 您必须向 LangSmith 提供OIDC、email和profile范围。我们使用这些来为您的用户获取必要的用户信息和电子邮件。
• 您需要在 IdP 中将回调 URL 设置为 http://<host>/api/v1/oauth/custom-oidc/callback，其中 host 是您为 LangSmith 实例配置的域或 IP。这是您的 IdP 在用户完成身份验证后将用户重定向到的位置。
• 您需要在values.yaml文件中提供oauthClientId、oauthClientSecret、hostname和oauthIssuerUrl。这是您配置 LangSmith 实例的位置。

Helm

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"

Docker

# 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

会话长度控制

注意

本节中的所有环境变量都适用于platform-backend服务，可以通过 Helm 中的platformBackend.deployment.extraEnv添加。

• 默认情况下，会话长度由身份提供商返回的身份令牌的过期时间控制。
• 大多数设置应使用刷新令牌将会话长度延长到身份令牌过期时间之外，最长可达OAUTH_SESSION_MAX_SEC，这可能需要通过添加到oauthScopes（Helm）或OAUTH_SCOPES（Docker）来包含offline_access范围。
• OAUTH_SESSION_MAX_SEC（默认 1 天）可覆盖，最长为一周（604800）。
• 对于不支持刷新令牌的身份提供商设置，将OAUTH_OVERRIDE_TOKEN_EXPIRY="true"设置为会话长度，将忽略身份令牌过期时间。

身份提供商 (IdP) 设置

Google Workspace

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

注意

您必须拥有组织 Google Cloud Platform (GCP) 账户的管理员级别访问权限才能创建新项目，或者拥有为现有项目创建和配置 OAuth 2.0 凭据的权限。我们建议您创建一个新项目来管理访问权限，因为每个 GCP 项目只有一个 OAuth 同意屏幕。

1. 创建一个新的 GCP 项目，请参阅 Google 文档主题创建和管理项目
2. 创建项目后，在 Google API 控制台中打开凭据页面（确保左上角的项目是正确的）
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 或复制并安全保存客户端 ID（以.apps.googleusercontent.com结尾）和客户端密钥。如果需要，您稍后可以访问这些信息。
8. 从左侧导航菜单中选择OAuth 同意屏幕
   1. 选择内部作为应用程序类型。如果您选择公开，任何拥有 Google 账户的人都可以登录。
   2. 输入一个描述性的应用程序名称。此名称会在用户登录时显示在同意屏幕上。例如，使用LangSmith或<组织名称> 的 LangSmith SSO。
   3. 验证 Google API 的范围是否仅列出 email、profile 和 openid 范围。只有这些范围是单点登录所需的。如果您授予额外的范围，会增加敏感数据暴露的风险。
9. （可选）控制组织内谁有权访问 LangSmith：https://admin.google.com/ac/owl/list?tab=configuredApps。有关更多详细信息，请参阅Google 的文档。
10. 配置 LangSmith 以使用此 OAuth 应用程序。例如，以下是用于 Kubernetes 配置的config值：
    1. oauthClientId: 客户端 ID (以.apps.googleusercontent.com结尾)
    2. oauthClientSecret: 客户端密钥
    3. hostname: 您的实例域名，例如https://langsmith.yourdomain.com (无尾随斜杠)
    4. oauthIssuerUrl: https://#
    5. oauth.enabled: true
    6. authType: mixed

不带客户端密钥（PKCE）（已弃用）

如果可能，我们建议使用客户端密钥运行（以前我们不支持此功能）。但是，如果您的 IdP 不支持此功能，您可以使用带 PKCE 的授权码流程。

此流程不需要客户端密钥——有关需要密钥的替代方案，请参见上文。

要求

使用 LangSmith 的 OAuth SSO 有几个要求

• 您的 IdP 必须支持带 PKCE 的授权码流程（例如，Google 不支持此流程，但请参阅下方，了解 Google 支持的替代配置）。这通常在您的 OAuth 提供商中显示为配置“单页应用程序 (SPA)”。
• 您的 IdP 必须支持使用外部发现/颁发者 URL。我们将使用它来获取您的 IdP 所需的路由和密钥。
• 您必须向 LangSmith 提供OIDC、email和profile范围。我们使用这些来为您的用户获取必要的用户信息和电子邮件。
• 您需要在 IdP 中将回调 URL 设置为 http://<host>/oauth-callback，其中 host 是您为 LangSmith 实例配置的域或 IP。这是您的 IdP 在用户完成身份验证后将用户重定向到的位置。
• 您需要在values.yaml文件中提供oauthClientId和oauthIssuerUrl。这是您配置 LangSmith 实例的位置。

Helm

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

Docker

# In your .env file
AUTH_TYPE=oauth
OAUTH_CLIENT_ID=your-client-id
OAUTH_ISSUER_URL=https://your-issuer-url