LangChain 中文文档

主题

使用 OAuth2.0 和 OIDC 设置单点登录 (SSO)

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

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

带有 OAuth SSO 的 LangSmith 用户界面

概述 ​

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

目前，LangSmith 自托管版本不支持从 SSO 模式切换回基础身份验证模式。我们也不支持从带有客户端密钥的 OAuth 模式切换到不带客户端密钥的 OAuth 模式，反之亦然。最后，我们不支持同时启用基础身份验证和 OAuth。在启用 OAuth 时，请确保禁用基础身份验证配置。

使用客户端密钥（推荐） ​

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

前提条件 ​

  • 您必须是自托管且处于企业版计划。
  • 您的 IdP 必须支持带有客户端密钥的授权码流程。
  • 您的 IdP 必须支持使用外部发现/颁发者 URL。我们将使用此 URL 来获取您的 IdP 的必要路由和密钥。
  • 您必须向 LangSmith 提供 OIDC、email 和 profile 作用域。我们使用这些来获取用户的必要信息和电子邮件。

LangSmith SSO 仅支持通过 https 协议。

配置 ​

  • 您需要在您的 IdP 中将回调 URL 设置为 https://<host>/api/v1/oauth/custom-oidc/callback，其中 host 是您为 LangSmith 实例配置的域名或 IP 地址。这是用户通过身份验证后，您的 IdP 将重定向用户的位置。
  • 您需要在 values.yaml 文件中提供 oauthClientId、oauthClientSecret、hostname 和 oauthIssuerUrl。这是您配置 LangSmith 实例的位置。
  • 如果您尚未配置带有客户端密钥的 Oauth，或者如果您只有个人组织，则必须提供一个电子邮件地址，以分配为新配置的 SSO 组织的初始组织管理员。如果您是从基础身份验证升级，则将重用您现有的组织。
yaml
config:
  authType: mixed
  hostname: https://langsmith.example.com
  initialOrgAdminEmail: test@email.com # 如果需要请设置此项
  oauth:
    enabled: true
    oauthClientId: <YOUR CLIENT ID>
    oauthClientSecret: <YOUR CLIENT SECRET>
    oauthIssuerUrl: <YOUR DISCOVERY URL>
    oauthScopes: "email,profile,openid"
bash
# 在您的 .env 文件中
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

会话时长控制 ​

本节中的所有环境变量都用于 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" 将使用 OAUTH_SESSION_MAX_SEC 作为会话时长，忽略身份令牌的过期时间。

覆盖 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：

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"}'

Google Workspace IdP 设置 ​

您可以使用 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 或 <组织名称> SSO for LangSmith。
    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: 您的 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) 配置

配置步骤 ​

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

通过 Okta 集成网络（推荐）

有关 SCIM 设置的详细信息，请参阅[为您的组织设置 SCIM](/langsmith/user-management#set-up-scim-for-your-organization)。

此配置方法是与 Okta 一起使用 SCIM 所必需的。

  1. 登录 Okta。
  2. 在右上角，选择 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. 填写 登录选项：
    • 应用程序用户名格式：电子邮件。
    • 更新应用程序用户名于：创建和更新。
    • 允许用户安全地查看其密码：保持未选中。
  13. 点击保存。
  14. 配置 LangSmith 以使用此 OAuth 应用程序（有关 initialOrgAdminEmail 的详细信息，请参阅通用配置部分）：
yaml
config:
  authType: mixed
  hostname: https://langsmith.example.com # 您的实例域名（注意末尾没有斜杠）
  initialOrgAdminEmail: test@email.com # 如果需要请设置此项
  oauth:
    enabled: true
    oauthClientId: "Client ID" # (以 `0o` 开头)
    oauthClientSecret: "Client secret"
    oauthIssuerUrl: "https://company-7422949.okta.com" # 您的 Okta 实例 URL
    oauthScopes: "email,profile,openid"
bash
# 在您的 .env 文件中
AUTH_TYPE=mixed
INITIAL_ORG_ADMIN_EMAIL=test@email.com # 如果需要请设置此项
LANGSMITH_URL=https://langsmith.example.com # 您的实例域名（注意末尾没有斜杠）
OAUTH_CLIENT_ID="Client ID" # (以 `0o` 开头)
OAUTH_CLIENT_SECRET="Client secret"
OAUTH_ISSUER_URL="https://company-7422949.okta.com" # 您的 Okta 实例 URL
OAUTH_SCOPES=email,profile,openid
有关 SCIM 设置的详细信息，请参阅[为您的组织设置 SCIM](/langsmith/user-management#set-up-scim-for-your-organization)。

通过自定义应用集成

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 下的默认 URI。
  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 的详细信息，请参阅通用配置部分）：
yaml
config:
  authType: mixed
  hostname: https://langsmith.example.com # 您的实例域名（注意末尾没有斜杠）
  initialOrgAdminEmail: test@email.com # 如果需要请设置此项
  oauth:
    enabled: true
    oauthClientId: "Client ID" # (以 `0o` 开头)
    oauthClientSecret: "Client secret"
    oauthIssuerUrl: "https://company-7422949.okta.com" # 您的 Okta 实例 URL
    oauthScopes: "email,profile,openid"
bash
# 在您的 .env 文件中
AUTH_TYPE=mixed
INITIAL_ORG_ADMIN_EMAIL=test@email.com # 如果需要请设置此项
LANGSMITH_URL=https://langsmith.example.com # 您的实例域名（注意末尾没有斜杠）
OAUTH_CLIENT_ID="Client ID" # (以 `0o` 开头)
OAUTH_CLIENT_SECRET="Client secret"
OAUTH_ISSUER_URL="https://company-7422949.okta.com" # 您的 Okta 实例 URL
OAUTH_SCOPES=email,profile,openid

SP 发起的 SSO ​

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

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

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

此流程不需要 客户端密钥。有关替代工作流程，请参阅使用客户端密钥。

要求 ​

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

  • 您的 IdP 必须支持 带有 PKCE 的授权码 流程（例如，Google 不支持此流程，但请参阅上文了解 Google 支持的替代配置）。这通常在您的 OAuth 提供商中显示为配置“单页应用程序 (SPA)”。
  • 您的 IdP 必须支持使用外部发现/颁发者 URL。我们将使用此 URL 来获取您的 IdP 的必要路由和密钥

LangChain 中文文档

Copyright © 王码码