跳到主要内容

配置 Gmail OAuth 认证

本指南将引导您创建用于 Gmail OAuth 认证的 Google Cloud 应用。OAuth 相比传统密码认证更安全。

前置条件​

  • Google 账户（个人或 Google Workspace）
  • 可访问 Google Cloud Console
  • Perfex CRM 安装 URL（用于配置 redirect URI）

分步配置​

步骤 1：创建 Google Cloud 项目​

  1. 访问 Google Cloud Console
  2. 点击页面顶部的项目下拉菜单
  3. 点击 "New Project"
  4. 输入项目名称（如 "Perfex Mailbox OAuth"）
  5. 点击 "Create"
  6. 等待项目创建完成后选中该项目

步骤 2：启用 Gmail API​

  1. 在 Google Cloud Console 中进入 "APIs & Services" > "Library"
  2. 搜索 "Gmail API"
  3. 在结果中点击 "Gmail API"
  4. 点击 "Enable"
  5. 等待 API 启用完成

步骤 3：配置 OAuth 同意屏幕​

  1. 进入 "APIs & Services" > "OAuth consent screen"
  2. 选择 "External" 用户类型（若有 Google Workspace 账户，也可选 "Internal"）
  3. 点击 "Create"
  4. 填写必填信息：
    • App name：输入应用名称（如 "Perfex CRM Mailbox"）
    • User support email：您的邮箱
    • Developer contact information：您的邮箱
  5. 点击 "Save and Continue"
  6. 在 "Scopes" 页面点击 "Add or Remove Scopes"
  7. 添加以下作用域：
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
  8. 点击 "Update"，再点击 "Save and Continue"
  9. 在 "Test users" 页面（若使用 External 应用类型）：
    • 将您的 Gmail 地址添加为测试用户
    • 点击 "Save and Continue"
  10. 检查后点击 "Back to Dashboard"

步骤 4：创建 OAuth 2.0 凭据​

  1. 进入 "APIs & Services" > "Credentials"
  2. 点击 "Create Credentials" > "OAuth client ID"
  3. 选择 "Web application" 应用类型
  4. 输入 OAuth 客户端名称（如 "Perfex Mailbox Client"）
  5. 在 "Authorized redirect URIs" 下点击 "Add URI"
  6. 添加 redirect URI，格式为：
https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

将 your-domain.com 替换为实际 Perfex CRM 域名。

  1. 点击 "Create"
  2. 重要：复制并妥善保存：
    • Client ID（后续需要）
    • Client Secret（后续需要，点击 "Show" 查看）

步骤 5：在 Perfex CRM 中配置​

  1. 进入 Perfex CRM 管理后台
  2. 进入 Mailbox > Configuration
  3. 选择 "OAuth2" 认证方式
  4. 选择 "Gmail" 提供商
  5. 在 "Gmail Client ID" 字段输入 Client ID
  6. 在 "Gmail Client Secret" 字段输入 Client Secret
  7. 点击 "Save Configuration"
  8. 点击 "Connect Gmail" 按钮
  9. 在 Google 弹出窗口中授权应用
  10. 应显示连接成功的消息

重要限制与注意事项​

Google 测试应用限制​

These limitations are imposed by Google, not by our software.

  1. Token 过期（7 天） - 未验证应用（测试模式应用）的 OAuth token 在 7 天 后过期。7 天后用户需重新授权连接。此为 Google 对未验证应用的安全策略。

  2. 测试用户限制 - 仅可添加为 "Test users" 的用户可使用 OAuth 应用。最多 100 个测试用户。此限制在应用验证并发布前均适用。

  3. 应用验证流程 - 若要取消 7 天 token 过期，需提交应用进行 Google 验证。验证通常需 数周（约 4–8 周）。Google 会审核应用的安全性与合规性。

应用验证与发布​

要解除限制：

  1. 提交验证

    • 在 Google Cloud Console 进入 "OAuth consent screen"
    • 点击 "PUBLISH APP" 按钮
    • 填写验证表单，包括：
      • 应用用途与功能
      • 隐私政策 URL
      • 服务条款 URL
      • 演示视频（可选但建议）
    • 提交审核

  2. 验证时间

    • 初审：约 1–2 周
    • 补充信息请求：视情况而定（若 Google 需澄清）
    • 最终批准：通常总计 4–8 周

  3. 验证后

    • Token 不再 7 天后过期
    • 无测试用户限制
    • 任意 Gmail 用户均可使用应用

生产模式与测试模式​

  • 测试模式：配置快捷，但 token 每 7 天过期
  • 生产模式：需验证，但 token 不会过期
  • 您可自行选择 - 本软件两种模式均支持

Token 刷新​

模块会在可能时自动刷新 token。但：

  • 未验证应用：Token 7 天后过期，需手动重新授权
  • 已验证应用：Token 自动刷新，无需用户操作

备注​

  • redirect URI 必须与 Google Cloud Console 中配置的完全一致
  • 妥善保管 Client Secret，切勿公开
  • 若更换域名，请在 Google Cloud Console 中更新 redirect URI
  • OAuth 流程由 Google 处理，模块仅负责发起请求并接收回调

故障排除​

"Redirect URI mismatch" 错误：

  • 确认 Google Cloud Console 中的 redirect URI 完全一致：https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
  • 检查尾斜杠及 HTTP/HTTPS 是否一致

7 天后出现 "Token expired"：

  • 未验证应用属预期行为（Google 政策）
  • 再次点击 "Connect Gmail" 重新授权
  • 若希望避免，可提交应用进行 Google 验证

"Access blocked" 错误：

  • 确认已将自己邮箱加入 "Test users"（未验证应用）
  • 检查 Gmail API 是否已在 Google Cloud 项目中启用

找不到 Gmail API：

  • 确认当前在正确的 Google Cloud 项目中
  • 在 API Library 中搜索 "Gmail"

延伸阅读​

信息

7 天 token 过期及测试用户限制为 Google 对未验证应用的安全策略，并非本软件设定。应用通过 Google 验证后，这些限制将解除。