使用 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_account | From address,Workspace 域的任何用户 | Google Workspace |
| 带有刷新令牌的用户凭据 | authorized_user | 授予刷新令牌的账户 | 个人 Gmail,或未启用委托的 Workspace |
创建服务账号密钥(Google Workspace)
- 在 Google Cloud 控制台中,打开您的项目,前往 IAM & Admin > Service accounts,并创建一个服务账号,例如
casdoor-mail。它不需要任何角色。 - 打开该服务账号。在 Details 选项卡上,复制 Unique ID,即其客户端 ID。在 Keys 选项卡上,点击 Add key > Create new key > JSON,并保留下载的文件。
- 在 Google 管理控制台中,前往 Security > Access and data control > API controls > Manage Domain Wide Delegation,并点击 Add new。输入客户端 ID 和范围
https://mail.google.com/,然后点击 Authorize。
委托可能需要几分钟才能生效。
创建用户凭据(个人 Gmail)
-
在 Google Cloud 控制台中,配置项目的 OAuth 同意屏幕,并创建一个类型为 Desktop app 的 OAuth 客户端 ID。下载其 JSON 文件。
-
通过使用发送邮件的账户登录,获取针对
https://mail.google.com/范围的刷新令牌。使用 gcloud CLI:gcloud auth application-default login \
--client-id-file=client_secret.json \
--scopes=https://mail.google.com/ -
gcloud 将凭据写入其配置文件夹中的
application_default_credentials.json(Linux 和 macOS 上是~/.config/gcloud/,Windows 上是%APPDATA%\gcloud\)。该文件包含"type": "authorized_user"、客户端 ID、客户端密钥和刷新令牌。
当项目的同意屏幕处于 Testing 状态时,Google 会在 7 天后使刷新令牌过期。发布应用以保持令牌有效。
在 Casdoor 中添加提供商
-
在 Casdoor 管理控制台中,前往 Identity > Providers 并添加一个提供商。
-
将 Category 设置为
Email,将 Type 设置为Gmail。Casdoor 会自动填充主机和端口。 -
填写以下字段:
字段 值 Google JSON key 服务账号密钥或用户凭据的 JSON 文件内容 From address 发送邮件的邮箱。对于服务账号,Casdoor 以此用户身份登录。对于用户凭据,请使用授予令牌的账户地址或其别名之一 From name (可选)发件人显示名称 Host smtp.gmail.comPort 587SSL mode Auto,即在端口 587 上使用 STARTTLS -
编写 Email title 和 Email content。请参阅 Templates。
-
保存提供商.
Enable proxy 选项会使令牌请求和 SMTP 连接均通过 Casdoor 的 SOCKS5 代理发送。参见 Proxy。
验证结果
- 点击 Test SMTP Connection。Casdoor 会获取令牌并以 From address 的身份登录 SMTP,但不会发送邮件。
- 点击 Send Testing Email 并检查消息是否到达 Test Email 邮箱。
然后将提供商添加到你的应用中。参见 Add providers to an application。
故障排除
| Error | Cause |
|---|---|
the from address of the Gmail email provider must be the mailbox that sends the emails | From address 为空或不是电子邮件地址 |
the credentials of the Gmail email provider must be a Google JSON key | Google JSON key 不是有效的 JSON |
the credentials of the Gmail email provider must be a "service_account" or "authorized_user" JSON key | JSON 是另一种类型的密钥,例如 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 accepted | Gmail 拒绝了令牌。检查 From address 是否为令牌签发的账户 |