---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 为 OpenConnector 创建 Google OAuth app
description: 为
  Gmail、Drive、Calendar、Sheets、Docs、Slides、YouTube、Analytics、BigQuery 等 OOMOL
  OpenConnector Google provider 创建 OAuth credentials。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/openconnector-google-oauth-app/
markdown_url: https://oomol.com/zh-cn/docs/openconnector-google-oauth-app.md
---

# 为 OpenConnector 创建 Google OAuth app

自部署 OOMOL OpenConnector 需要连接用户的 Google 账号时，使用 Google OAuth app。一个 Google Cloud project 可以保存 Gmail、Google Drive、Google Calendar、Google Sheets、Google Docs、Google Slides、YouTube、Google Analytics、Google BigQuery 等 provider 使用的 OAuth client。

## OpenConnector services

| Service ID | Provider |
| --- | --- |
| `gmail` | Gmail |
| `googledrive` | Google Drive |
| `googlecalendar` | Google Calendar |
| `googlesheets` | Google Sheets |
| `googledocs` | Google Docs |
| `googleslides` | Google Slides |
| `youtube` | YouTube |
| `google_analytics` | Google Analytics |
| `google_bigquery` | Google BigQuery |

每个 service 在 OpenConnector 中单独保存 OAuth client config。如果同一个 Google OAuth client 已允许相同 redirect URI，并且已启用所需 API 和 scopes，你可以把同一组 client ID / client secret 保存给多个 Google service。

## 前置条件

- 一个正在运行的 OpenConnector runtime。
- 可以访问 Google Cloud project 的 Google 账号。
- 有权限配置 OAuth consent、启用 APIs、创建 OAuth credentials。
- 用户在浏览器中打开的 OpenConnector origin，例如 `http://localhost:3000` 或 `https://connect.example.com`。

## 第 1 步：确定 OpenConnector callback URL

本地测试时使用：

```text
http://localhost:3000/oauth/callback
```

公开 runtime 请先设置 `OOMOL_CONNECT_ORIGIN`，重启后使用：

```text
https://connect.example.com/oauth/callback
```

## 第 2 步：准备 Google Cloud project

在 [Google Cloud Console](https://console.cloud.google.com/) 中：

1. 创建或选择一个 project。
2. 打开 **APIs & Services**。
3. 启用 OpenConnector service 需要的 API，例如 Gmail API、Google Drive API、Google Calendar API、Google Sheets API、YouTube Data API、Google Analytics Data API 或 BigQuery API。
4. 打开 **OAuth consent screen**，按 Google 要求配置 app name、support email、audience、contact information 和 test users。
5. 添加 OpenConnector service 需要的 scopes，或在启动 OAuth 授权时由 Google 展示这些 scopes。

敏感或受限 scopes 在广泛生产使用前可能需要 Google verification。本地使用或内部测试时，请按你的 Google 账号类型使用 testing 或 internal 状态。

## 第 3 步：创建 OAuth credentials

在 **APIs & Services > Credentials** 中：

1. 选择 **Create credentials**。
2. 选择 **OAuth client ID**。
3. Application type 选择 **Web application**。
4. 在 authorized redirect URIs 中添加 OpenConnector 的准确 callback URL。
5. 创建 client。
6. 复制 client ID 和 client secret。

Google 官方文档见 [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)。

## 第 4 步：在 OpenConnector 中保存 client

优先在 OpenConnector Web 控制台中配置目标 service：

1. 打开 OpenConnector Web 控制台，例如 `http://localhost:3000`。
2. 打开 **Providers**，选择 **Gmail** 或其他 Google provider。
3. 点击 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 粘贴 Google client ID 和 client secret。
5. 点击 **Save OAuth Client**。

如果要把同一 Google OAuth client 用到其他 Google provider，请在对应 Google provider 页面重复这些步骤。

## 第 5 步：连接并测试

保存 OAuth client 后，在 Google provider 页面点击 **Connect**。完成 Google consent，回到 OpenConnector，并确认 provider 页面显示账号已连接。

Gmail 可用 `gmail.get_profile` 或 `gmail.list_labels` 做低风险测试。运行 action 前，先在控制台 action 详情中确认准确输入。

## 排查建议

| 现象 | 检查项 |
| --- | --- |
| `redirect_uri_mismatch` | Google 收到的 URI 必须和 OAuth client 中的 authorized redirect URI 完全一致。确认它是 `<openconnector-origin>/oauth/callback`。 |
| Google 显示 app 未验证 | 使用允许的 test users 测试，能用 internal mode 时使用 internal mode；广泛使用前完成 Google verification。 |
| Google 没有发 refresh token | 重新连接账号。需要 refresh token 的 OpenConnector Google provider 会在定义中请求 offline access 和 consent。 |
| Google action 提示权限不足 | 在 Google Cloud 启用所需 API，添加或批准所需 scope，然后重新连接账号。 |
| 执行时用了错误 Google 账号 | 使用已登录目标 Google 账号的浏览器 profile 重新连接。 |

请把 Google client secret 放在密钥管理系统中，并在 OpenConnector 中保存 OAuth client 前设置 `OOMOL_CONNECT_ENCRYPTION_KEY`。