管理设置 - 管理 OAuth 客户端

在 Looker 中，管理员可以使用管理 OAuth 客户端页面为外部应用管理基于身份的 OAuth 2.0 访问权限，而无需创建 API 密钥或使用 API Explorer。本文档介绍了如何启用预配置的应用、注册自定义 OAuth 客户端以及管理令牌撤消。

管理 OAuth 客户端页面位于 Looker 管理面板的身份验证部分。它提供了一个集中式界面，用于授予对 Looker CLI、AI 智能体 Model Context Protocol (MCP) 客户端和商业智能 (BI) 连接器等开发者工具的访问权限。

注意： 如果您拥有的权限仅允许您访问管理控制台中的部分页面（例如 manage_schedules、manage_themes 或 see_admin），但您没有管理员角色，则您可能无法在管理控制台中看到此处所述的页面。

要求

如需访问和管理管理 OAuth 客户端页面，必须满足以下要求：

• 您的 Looker 实例必须由 Looker 托管。不支持客户托管的 Looker 实例。
• 您必须在 Looker 实例中拥有管理员角色。

概览

管理 OAuth 客户端页面将客户端应用整理到两个标签页中：

• 应用库：一个目录，其中包含预配置的、由 Looker 管理的 OAuth 应用，包括 AI 智能体 Model Context Protocol (MCP) 客户端、商业智能 (BI) 连接器和开发者工具。
• 自定义客户端：一个管理界面，用于注册和配置您自己的自定义 OAuth 客户端应用，并提供可自定义的回调重定向 URI 和群组访问权限控制。

您可以使用页面顶部的搜索栏，实时过滤两个标签页中的应用。

“应用库”标签页

Application Library（应用库）标签页包含由 Looker 维护的预配置 OAuth 客户端。我们建议您在创建自定义客户端之前，先查看应用库标签页。如果您要连接的工具已在库中预先配置，则可以直接启用，而无需注册新的自定义客户端，除非您需要使用不同的重定向 URI 或端口。

应用库包含适用于以下集成的预配置客户端：

• AI 智能体 MCP 客户端：Cursor、VS Code、Claude Code、Claude Desktop、ChatGPT、Gemini CLI、Cline、Windsurf、Antigravity 和 Looker Extension for VS Code。
• BI 连接器：关联工作表、数据洞察、Tableau Desktop、Microsoft Power BI 和 Microsoft Excel。
• 开发者工具：Looker CLI。

启用和停用库应用

应用库中的每个预配置客户端应用都有一个启用开关：

• 启用：启用该开关，以允许用户使用 OAuth 从该客户端应用向 Looker 进行身份验证。
• 停用：停用开关，以屏蔽来自该客户端应用的授权请求。停用应用会立即撤消并使为该应用向用户发放的所有有效 OAuth 令牌失效。

注意： 应用库中预配置的应用无法删除。只能启用或停用。

每个预配置客户端应用的客户端 ID 会显示在相应行中。您可以复制客户端 ID 以便在客户端配置中使用，但库应用的客户端 ID 是不可变的，无法修改。

与“BI 连接器”页面同步

BI 连接器（包括关联工作表、数据洞察、Tableau Desktop、Microsoft Power BI 和 Microsoft Excel）的启用状态会在管理 OAuth 客户端页面和 BI 连接器页面之间自动同步：

• 在管理 OAuth 客户端页面上更改 BI 连接器开关的启用状态后，BI 连接器页面上对应的连接器开关会自动更新。
• 在 BI 连接器页面上更改 BI 连接器开关的启用状态后，系统会自动在管理 OAuth 客户端页面上更新其状态。

注意： BI 连接器页面仍可用于配置出站启用关联工作表快捷链接设置。

重定向 URI 和动态端口配置

Looker 要求 OAuth 重定向 URI 与注册值完全匹配，并且不支持通配符重定向 URI。

• 标准 BI 连接器：使用与服务的官方身份验证端点匹配的预配置、不可变重定向 URI。
• AI 智能体和 MCP 客户端：某些 AI 工具（例如 Claude Code 或 Cline）在发起 OAuth 重定向时默认使用动态或临时本地端口。为了适应这些工具，Looker 为每个库客户端预注册了一个固定的默认端口（例如，Claude Code 和 Cline 使用端口 8080，Gemini CLI 使用端口 7777）。

如需使用需要固定端口的预配置库客户端，请选择以下选项之一：

1. 将客户端配置为使用预注册的静态端口：在客户端应用设置或启动标志中，指定预注册的端口（例如，使用 --callback-port 8080 运行 Claude Code）。
2. 注册自定义客户端：如果您想使用其他端口或自定义回调网址，请在自定义客户端标签页上注册一个新客户端，并指定您偏好的重定向 URI。

“自定义客户端”标签页

通过自定义客户端标签页，您可以为内部工具、专有集成或应用库中未提供的第三方应用注册和管理自定义 OAuth 2.0 客户端应用。

注册自定义 OAuth 客户端

如需注册新的自定义 OAuth 客户端，请按照以下步骤操作：

1. 在管理控制台中，前往身份验证部分，然后选择管理 OAuth 客户端。
2. 选择自定义客户端标签页。
3. 点击 Add New（新增）。
4. 在侧边栏中，填写以下字段：
   • 客户端 ID：为您的应用输入一个唯一的字符串标识符。客户端 ID 不能以 com.looker. 开头，该前缀预留给 Looker 管理的应用。
   • Client Name（客户端名称）：为应用输入一个描述性显示名称。
   • 说明（可选）：输入简要说明，解释应用的用途。
   • 重定向 URI：输入一个或多个已获授权的回调 URI（例如 https://mycompany.com/oauth/callback 或 http://localhost:8080/callback）。您可以输入多个重定向 URI，以支持不同的环境或端口。
   • 仅限群组 ID（可选）：输入 Looker 用户群组的数字 ID。如果指定了数字 ID，则只有属于该群组的用户才能使用此应用授权和验证 Looker。
5. 点击添加以创建自定义客户端。

查看客户端详细信息

如需查看任何自定义客户端应用的详细信息，请按以下步骤操作：

1. 在自定义客户端标签页中，点击表格中相应客户端所在行中的 chevron_right V 形图标。
2. 系统会打开一个侧边栏，其中显示客户端名称、客户端 ID、说明、已获授权的重定向 URI 的完整列表，以及群组 ID 限制（如果已配置）。

修改自定义客户端

如需更新现有的自定义 OAuth 客户端应用，请按以下步骤操作：

1. 在自定义客户端标签页中，找到客户端应用，然后点击其所在行中的 edit 修改图标。

2. 在侧边编辑面板中，根据需要更新客户端名称、说明、重定向 URI 或限制为群组 ID 字段。

   注意： 注册后，客户端 ID 字段便无法修改。如果您需要更改客户端 ID，请删除该客户端并注册一个新客户端。

3. 点击更新以保存更改。

删除自定义客户端

如需移除自定义 OAuth 客户端应用，请按以下步骤操作：

1. 在自定义客户端标签页中，找到相应客户端应用，然后点击其所在行中的 delete 删除（垃圾桶）图标。
2. 在确认对话框中点击删除。

警告： 删除自定义客户端会从 Looker 中永久移除客户端注册，并立即撤消为该应用颁发的所有有效 OAuth 授权代码、访问令牌和刷新令牌。

令牌失效和安全性

为了维护关联应用之间的安全性，Looker 会自动强制撤消令牌。当管理员删除自定义客户端应用或在应用库或自定义客户端标签页中停用应用时，Looker 会立即撤消为该应用向所有用户发放的所有有效 OAuth 刷新令牌。与该应用关联的所有授权代码都会永久失效。

注意： 如果删除或停用应用，则无法生成新的访问令牌，并且任何已签发的访问令牌都将在 60 分钟内过期。

如果用户或应用尝试使用已撤消的凭据进行连接，Looker 会拒绝授权，并返回一个错误，指明未找到或未启用 OAuth 客户端。