> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 OAuth2.0 和 OIDC 设置单点登录

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

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

<img src="https://mintcdn.com/hhh-8c10bf0c/lQoj_T05pUgIcyPg/langsmith/images/langsmith-ui-sso.png?fit=max&auto=format&n=lQoj_T05pUgIcyPg&q=85&s=0d9e818dfcaca2778afefc9ad94f3019" alt="LangSmith UI with OAuth SSO" width="1596" height="994" data-path="langsmith/images/langsmith-ui-sso.png" />

## 概述

<Note>
  您可以将[基础身份验证](/langsmith/self-host-basic-auth)安装升级到此模式，但不能从[无身份验证](/langsmith/authentication-methods#none)安装升级。要升级，只需移除基础身份验证配置，并添加如下所示的必需配置参数。之后，用户将*只能*通过 OAuth 登录。**为了在升级后保持访问权限，您必须能够使用先前通过基础身份验证登录过的电子邮件地址通过 OAuth 登录。**
</Note>

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

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

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

### 前提条件

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

<Note>
  LangSmith 单点登录仅支持通过 `https` 协议。
</Note>

### 配置

* 您需要在您的身份提供商中将回调 URL 设置为 `https://<host>/api/v1/oauth/custom-oidc/callback`，其中 `host` 是您为 LangSmith 实例配置的域名或 IP 地址。这是用户身份验证后，您的身份提供商将重定向用户的位置。
* 您需要在 `values.yaml` 文件中提供 `oauthClientId`、`oauthClientSecret`、`hostname` 和 `oauthIssuerUrl`。这是您配置 LangSmith 实例的位置。
* 如果您**尚未**配置使用客户端密钥的 OAuth，或者您只有个人组织，则必须提供一个电子邮件地址，以分配为新配置的单点登录组织的初始组织管理员。如果您是从基础身份验证升级，您现有的组织将被重用。

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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 Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .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
  ```
</CodeGroup>

### 会话时长控制

<Note>
  本节中的所有环境变量都用于 `platform-backend` 服务，可以在 Helm 中使用 `platformBackend.deployment.extraEnv` 添加。
</Note>

* 默认情况下，会话时长由身份提供商返回的身份令牌的过期时间控制。
* 大多数设置应使用刷新令牌，以将会话时长延长至超过身份令牌的过期时间，最长可达 `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 身份提供商设置

您可以使用 Google Workspace 作为单点登录提供商，通过 [OAuth2.0 和 OIDC](https://developers.google.com/identity/openid-connect/openid-connect) 实现，无需 PKCE。

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

1. 创建一个新的 GCP 项目，请参阅 Google 文档主题[创建和管理项目](https://cloud.google.com/resource-manager/docs/creating-managing-projects)。

2. 创建项目后，打开 Google API 控制台中的[凭据](https://console.developers.google.com/apis/credentials)页面（确保左上角的项目是正确的）。

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 单点登录`。
   3. 验证 Google API 的范围是否仅列出电子邮件、个人资料和 openid 范围。单点登录仅需要这些范围。如果授予额外的范围，会增加暴露敏感数据的风险。

9. （可选）控制组织内谁可以访问 LangSmith：[https://admin.google.com/ac/owl/list?tab=configuredApps](https://admin.google.com/ac/owl/list?tab=configuredApps)。有关更多详细信息，请参阅[Google 的文档](https://support.google.com/a/answer/7281227?hl=en\&fl=1\&sjid=9554153972856467090-NA)。

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 身份提供商设置

#### 支持的功能

* 身份提供商发起的单点登录
* 服务提供商发起的单点登录
* 即时配置（请参阅[在单点登录组织中管理用户访问](/langsmith/jit-invite-sso)）

#### 配置步骤

更多信息，请参阅 Okta 的[文档](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)。
如果您有任何问题或疑问，请通过 [support.langchain.com](https://support.langchain.com) 联系支持。

<div id="via-okta-integration-network">
  <b>通过 Okta 集成网络（推荐）</b>
</div>

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

<Note>
  此配置方法是使用 Okta 的 SCIM 所必需的。
</Note>

1. 登录 [Okta](https://login.okta.com/)。
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](/langsmith/user-management#set-up-scim-for-your-organization)）填写 `LangSmithUrl`：上述 URL 中的 `<langsmith_url>` 部分，例如 `langsmith.yourdomain.com`。
9. 在 `应用程序可见性` 下，保持复选框未选中。
10. 选择 `下一步`。
11. 选择 `OpenID Connect`。
12. 填写 `登录选项`：
    * `应用程序用户名格式`：`电子邮件`。
    * `更新应用程序用户名于`：`创建和更新`。
    * `允许用户安全查看其密码`：保持**未选中**。
13. 点击**保存**。
14. 配置 LangSmith 以使用此 OAuth 应用程序（有关 `initialOrgAdminEmail` 的详细信息，请参阅[通用配置部分](#configuration)）：

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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 Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .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
  ```
</CodeGroup>

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

<div id="via-okta-custom-app-integration">
  <b>通过自定义应用集成</b>
</div>

<Warning>
  SCIM 与此配置方法不兼容。请参阅[**通过 Okta 集成网络**](#via-okta-integration-network)。
</Warning>

1. 以管理员身份登录 Okta，并转到 **Okta 管理控制台**。
2. 在 **应用程序** > **应用程序** 下，点击 **创建应用集成**。
3. 选择 **OIDC - OpenID Connect** 作为登录方法，选择 **Web 应用程序** 作为应用程序类型，然后点击 **下一步**。
4. 输入 `应用集成名称`（例如 `LangSmith`）。
5. 推荐：勾选 **核心授权 > 刷新令牌**（请参阅[会话时长控制](#session-length-controls)）。
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 或应用均可` 以启用身份提供商发起的登录。
13. （推荐）在 **常规 > 登录 > 电子邮件验证体验** 下，在 **回调 URI** 中填写 LangSmith URL，例如 `https://langsmith.yourdomain.com`。
14. 配置 LangSmith 以使用此 OAuth 应用程序（有关 `initialOrgAdminEmail` 的详细信息，请参阅[通用配置部分](#configuration)）：

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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 Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .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
  ```
</CodeGroup>

#### 服务提供商发起的单点登录

用户可以在 LangSmith 主页上使用 **通过单点登录登录** 按钮进行登录。

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

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

此流程*不*需要 `客户端密钥`。有关替代工作流程，请参阅[使用客户端密钥](#with-client-secret-recommended)。

### 要求

使用 LangSmith 进行 OAuth 单点登录有几个要求：

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

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  config:
    oauth:
      enabled: true
      oauthClientId: <YOUR CLIENT ID>
      oauthIssuerUrl: <YOUR DISCOVERY URL>
  ```

  ```bash Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .env 文件中
  AUTH_TYPE=oauth
  OAUTH_CLIENT_ID=your-client-id
  OAUTH_ISSUER_URL=https://your-issuer-url
  ```
</CodeGroup>

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\self-host-sso.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>