跳到主内容

使用 Gmail 发送邮件

本指南介绍如何在不使用应用专用密码的情况下,从 Gmail 或 Google Workspace 邮箱发送 Casdoor 的邮件。Gmail 类型使用 XOAUTH2 登录到 smtp.gmail.com:Casdoor 从 Google JSON 密钥获取针对 https://mail.google.com/ 范围的 OAuth 2.0 令牌,并以发件邮箱身份登录。


学习目标​

  • 创建一个可用于作为邮箱发送邮件的 Google JSON 密钥。
  • 在 Casdoor 中添加 Gmail 作为邮件提供商并进行测试。

前提条件​

  • 一个 Google Workspace 域和超级管理员,或个人 Gmail 账户
  • 一个 Google Cloud 项目
  • 拥有 Casdoor 管理控制台的管理员权限

关于 JSON 密钥​

Casdoor 接受两种类型的 Google JSON 密钥:

密钥JSON 中的 type作为...发送适用于
具有全域委托的服务账号密钥service_accountFrom address,Workspace 域的任何用户Google Workspace
带有刷新令牌的用户凭据authorized_user授予刷新令牌的账户个人 Gmail,或未启用委托的 Workspace

创建服务账号密钥(Google Workspace)​

  1. 在 Google Cloud 控制台中,打开您的项目,前往 IAM & Admin > Service accounts,并创建一个服务账号,例如 casdoor-mail。它不需要任何角色。
  2. 打开该服务账号。在 Details 选项卡上,复制 Unique ID,即其客户端 ID。在 Keys 选项卡上,点击 Add key > Create new key > JSON,并保留下载的文件。
  3. 在 Google 管理控制台中,前往 Security > Access and data control > API controls > Manage Domain Wide Delegation,并点击 Add new。输入客户端 ID 和范围 https://mail.google.com/,然后点击 Authorize。

委托可能需要几分钟才能生效。

创建用户凭据(个人 Gmail)​

  1. 在 Google Cloud 控制台中,配置项目的 OAuth 同意屏幕,并创建一个类型为 Desktop app 的 OAuth 客户端 ID。下载其 JSON 文件。

  2. 通过使用发送邮件的账户登录,获取针对 https://mail.google.com/ 范围的刷新令牌。使用 gcloud CLI:

    gcloud auth application-default login \
    --client-id-file=client_secret.json \
    --scopes=https://mail.google.com/
  3. gcloud 将凭据写入其配置文件夹中的 application_default_credentials.json(Linux 和 macOS 上是 ~/.config/gcloud/,Windows 上是 %APPDATA%\gcloud\)。该文件包含 "type": "authorized_user"、客户端 ID、客户端密钥和刷新令牌。

当项目的同意屏幕处于 Testing 状态时,Google 会在 7 天后使刷新令牌过期。发布应用以保持令牌有效。

在 Casdoor 中添加提供商​

  1. 在 Casdoor 管理控制台中,前往 Identity > Providers 并添加一个提供商。

  2. 将 Category 设置为 Email,将 Type 设置为 Gmail。Casdoor 会自动填充主机和端口。

  3. 填写以下字段:

    字段值
    Google JSON key服务账号密钥或用户凭据的 JSON 文件内容
    From address发送邮件的邮箱。对于服务账号,Casdoor 以此用户身份登录。对于用户凭据,请使用授予令牌的账户地址或其别名之一
    From name(可选)发件人显示名称
    Hostsmtp.gmail.com
    Port587
    SSL modeAuto,即在端口 587 上使用 STARTTLS
  4. 编写 Email title 和 Email content。请参阅 Templates。

  5. 保存提供商.

Enable proxy 选项会使令牌请求和 SMTP 连接均通过 Casdoor 的 SOCKS5 代理发送。参见 Proxy。

验证结果​

  1. 点击 Test SMTP Connection。Casdoor 会获取令牌并以 From address 的身份登录 SMTP,但不会发送邮件。
  2. 点击 Send Testing Email 并检查消息是否到达 Test Email 邮箱。

然后将提供商添加到你的应用中。参见 Add providers to an application。

故障排除​

ErrorCause
the from address of the Gmail email provider must be the mailbox that sends the emailsFrom address 为空或不是电子邮件地址
the credentials of the Gmail email provider must be a Google JSON keyGoogle JSON key 不是有效的 JSON
the credentials of the Gmail email provider must be a "service_account" or "authorized_user" JSON keyJSON 是另一种类型的密钥,例如 OAuth 客户端 ID 文件。参见 About the JSON key
oauth2: cannot fetch token 伴随 unauthorized_client缺少服务账号的全域委托,客户端 ID 不匹配,或缺少 https://mail.google.com/ 范围
oauth2: cannot fetch token 伴随 invalid_grant刷新令牌已被撤销或过期,或者 From address 不是 Workspace 域的用户
535 5.7.8 Username and Password not acceptedGmail 拒绝了令牌。检查 From address 是否为令牌签发的账户

另请参阅​