OneUptime SMTP OAuth 2.0 邮件发送配置完全指南Microsoft 365 与 Google Workspace 实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文是一份针对 OneUptime 自定义 SMTP 邮件服务器的完整配置指南聚焦于 OAuth 2.0 认证在 Microsoft 365Exchange Online与 Google Workspace 上的落地实践。读者将掌握 OneUptime 中 SMTP 的三种认证方式、OAuth 配置字段的完整含义、两大云邮件服务的端到端配置步骤以及常见报错的排查与安全最佳实践。OneUptime 支持通过自定义 SMTP 服务器发送告警、通知与状态页邮件。从源码看系统共提供三种 SMTP 认证方式由 SMTPAuthenticationType 枚举定义用户名与密码传统 SMTP AUTH、OAuthOAuth 2.0适用于 Microsoft 365 与 Google Workspace、以及None用于不需要认证的中继服务器。其中 OAuth 是当前企业环境中最重要的配置路径——许多组织出于安全考虑已禁用基础认证Basic Auth此时只有 OAuth 2.0 能让 OneUptime 正常投递邮件。OAuth 2.0 与两种授权类型Grant TypeOAuth 2.0 为 SMTP 提供了比密码更安全的认证方式尤其适合已经禁用基础认证的企业环境。OneUptime 通过 OAuthProviderType 枚举支持两种 OAuth 授权类型授权类型协议规范适用场景必填字段Client Credentials客户端凭据RFC 6749Microsoft 365 及大多数 OAuth 提供方Client ID、Client Secret、Token URL、ScopeJWT BearerJWT 载体断言RFC 7523Google Workspace 服务账号Client ID服务账号邮箱、Client Secret私钥、Token URL、Scope、Username要模拟的用户两种授权类型在 OneUptime 中的执行路径由 SMTPOAuthService.ts 统一实现fetchToken()根据providerType分发到fetchClientCredentialsToken()或fetchJWTBearerToken()。JWT Bearer 流程中OneUptime 会构造包含iss签发者服务账号邮箱、sub模拟的用户、scope、audToken URL、iat/exp声明的 JWT用私钥签名后以grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer向令牌端点换取 access_tokenClient Credentials 流程则直接以client_id、client_secret、scope、grant_typeclient_credentials请求令牌。OAuth 配置必填字段在 OneUptime 中配置带 OAuth 认证的 SMTP 时需要以下字段对应数据模型 ProjectSmtpConfig.ts 中的clientId、clientSecret、tokenUrl、scope、oauthProviderType等列字段说明HostnameSMTP 服务器地址PortSMTP 端口通常 587 用于 STARTTLS465 用于隐式 TLSUsername发件邮箱地址Authentication Type选择「OAuth」OAuth Provider TypeMicrosoft 365 选「Client Credentials」Google Workspace 选「JWT Bearer」Client IDOAuth 提供方中的应用/客户端标识Google 场景为服务账号邮箱Client SecretOAuth 提供方中的客户端密钥Google 场景为私钥Token URLOAuth 令牌端点地址ScopeSMTP 访问所需的 OAuth 作用域此外任何 SMTP 配置都必须提供fromEmail必填与fromName可选secure默认 true启用 SSL/TLS与description。OneUptime 还为配置提供了name项目内唯一与自动生成的slug字段。邮件投递的底层调用链了解配置落地前的调用链有助于理解为什么这些字段如此重要。OneUptime 的邮件发送分为「调度侧」与「投递侧」各业务模块如告警、状态页订阅调用 MailService.sendMail() 将邮件与选中的mailServerSMTP 配置打包序列化为SMTP_HOST、SMTP_PORT、SMTP_AUTH_TYPE、SMTP_CLIENT_ID、SMTP_CLIENT_SECRET、SMTP_TOKEN_URL、SMTP_SCOPE、SMTP_OAUTH_PROVIDER_TYPE等字段POST 到 Notification 服务的/api/notification/email/send接口。Notification 服务的 MailService.ts 接收请求后根据authType分支若为SMTPAuthenticationType.OAuth则调用createOAuthTransporter()——每次发送都会创建新的 transporter 以获取新鲜令牌源码注释明确说明「For OAuth, we need to create a new transporter each time to get fresh tokens」若为 UsernamePassword则直接使用账号密码构造 transporter。令牌获取由SMTPOAuthService.getAccessToken()完成并基于 RedisGlobalCache做跨容器共享缓存令牌在过期前 5 分钟TOKEN_BUFFER_SECONDS 300即视为失效并自动刷新。最终以 XOAUTH2 方式与 SMTP 服务器握手createXOAuth2Token()生成base64(userusername\x01authBearer accessToken\x01\x01)格式的认证串。值得注意的是fetchWithTimeout()在请求令牌前会通过DataSourceEgressGuard.assertUrlAllowed()校验 Token URL 的出口访问并禁止自动重定向这是出于防凭据外泄的考虑——Token URL 来自项目成员可编辑的配置携带 client secret 的请求不能发往未经验证的目标。若 Token URL 请求超过 30 秒FETCH_TIMEOUT_MS未响应会以用户可读的错误提示超时。配置 Microsoft 365Exchange Online要在 OneUptime 中使用 Microsoft 365 OAuth 发信需要先在 Microsoft Entra原 Azure AD注册应用并完成 Exchange Online 侧的授权。第一步在 Microsoft Entra 注册应用登录 Microsoft Entra 管理中心。进入IdentityApplicationsApp registrations。点击New registration。输入应用名称例如「OneUptime SMTP」。Supported account types选择「Accounts in this organizational directory only」仅本组织目录。Redirect URI留空Client Credentials 流程不需要。点击Register。注册完成后从Overview页面记下两个关键值Application (client) ID—— 即 OneUptime 中的 Client IDDirectory (tenant) ID—— 构造 Token URL 时需要。第二步创建 Client Secret在应用注册页进入Certificates secrets。点击New client secret。添加描述并选择过期时长。点击Add。立即复制 Secret 的值——它不会再次显示。第三步添加 SMTP 相关 API 权限进入API permissions。点击Add a permission。选择APIs my organization uses。搜索并选择Office 365 Exchange Online。选择Application permissions。勾选SMTP.SendAsApp。点击Add permissions。点击Grant admin consent for [你的组织]需要管理员权限。说明SMTP.SendAsApp 是应用级权限对应本文档强调的最小权限原则源码模型注释中也提到 OneUptime 支持MailTransportType.MicrosoftGraph这类 HTTP-API 传输方式通过 Microsoft Graph REST API 直发绕开 SMTP AUTH但本文聚焦 SMTP 传输场景。第四步在 Exchange Online 注册 Service Principal应用要在 Exchange Online 中真正具备发信能力必须注册 service principal 并授予邮箱访问权安装 Exchange Online PowerShell 模块Install-Module -Name ExchangeOnlineManagement -Force连接 Exchange OnlineImport-Module ExchangeOnlineManagement Connect-ExchangeOnline -Organization your-tenant-id注册 service principal使用Enterprise Applications中的 Object ID而不是 App Registrations 中的# 在 Microsoft Entra Enterprise Applications 你的应用 Object ID 中查找 New-ServicePrincipal -AppId application-client-id -ObjectId enterprise-app-object-id授予 service principal 以指定邮箱身份发信的完整邮箱权限# Grant full mailbox access to the service principal Add-MailboxPermission -Identity senderyourdomain.com -User service-principal-id -AccessRights FullAccess重要提示必须使用Add-MailboxPermission而非Add-RecipientPermission。Add-RecipientPermission只对收件人授予SendAs不足以让 service principal 通过 OAuth SMTP 发信——用它配置后发送时会遇到认证/访问错误。Add-MailboxPermission配合FullAccess才是真正有效的方案。第五步在 OneUptime 中配置在 OneUptime 中新建或编辑一条 SMTP 配置填写以下值字段值Hostnamesmtp.office365.comPort587Username已授予访问权限的邮箱地址如senderyourdomain.comAuthentication TypeOAuthOAuth Provider TypeClient CredentialsClient ID第一步中的 Application (client) IDClient Secret第二步中的 Secret 值Token URLhttps://login.microsoftonline.com/tenant-id/oauth2/v2.0/tokenScopehttps://outlook.office365.com/.defaultFrom Email与 Username 相同Secure (TLS)启用将tenant-id替换为第一步中记录的 Directory (tenant) ID。该 Token URL 与 Scope 的取值与数据模型中的默认说明一致见 ProjectSmtpConfig.ts 的tokenUrl、scope字段描述。配置 Google WorkspaceGoogle Workspace 要求使用**服务账号Service Account并启用域级委派Domain-wide Delegation**来代表用户发信——这是因为 Google 的 SMTP 服务器不支持针对 Gmail 的直接 Client Credentials 流程。前置条件Google Workspace 账号不是普通 Gmail——个人消费级 Gmail 账号不支持此方案Google Workspace 管理控制台的 Super Admin 权限可访问 Google Cloud Console。第一步创建 Google Cloud 项目进入 Google Cloud Console。点击项目下拉列表选择New Project。输入项目名称点击Create。选中刚创建的项目。第二步启用 Gmail API进入APIs ServicesLibrary。搜索「Gmail API」。点击Gmail API然后点击Enable。第三步创建服务账号进入APIs ServicesCredentials。点击Create CredentialsService account。输入服务账号名称和描述。点击Create and Continue。跳过可选步骤点击Done。第四步创建服务账号密钥点击刚创建的服务账号。进入Keys标签页。点击Add KeyCreate new key。选择JSON点击Create。安全保存下载的 JSON 文件其中包含client_id—— 客户端标识private_key—— 客户端密钥私钥。第五步启用域级委派在服务账号详情中点击Show Advanced Settings。记下Client ID数字形式的标识。勾选Enable Google Workspace Domain-wide Delegation。点击Save。第六步在 Google Workspace 管理控制台授权服务账号登录 Google Workspace 管理控制台。进入SecurityAccess and data controlAPI Controls。点击Manage Domain Wide Delegation。点击Add new。输入第五步中的Client ID。在OAuth Scopes中输入https://mail.google.com/。点击Authorize。注意域级委派的生效可能需要几分钟到最长 24 小时。第七步在 OneUptime 中配置在 OneUptime 中新建或编辑 SMTP 配置填写以下值字段值Hostnamesmtp.gmail.comPort587Username作为发件人的 Google Workspace 邮箱如notificationsyourdomain.com。服务账号将模拟该用户。Authentication TypeOAuthOAuth Provider TypeJWT BearerClient IDJSON 文件中的client_email如your-serviceyour-project.iam.gserviceaccount.comClient SecretJSON 文件中的private_key完整值包含-----BEGIN PRIVATE KEY-----与-----END PRIVATE KEY-----标记Token URLhttps://oauth2.googleapis.com/tokenScopehttps://mail.google.com/From Email与 Username 相同Secure (TLS)启用关键区别对 GoogleJWT Bearer而言Client ID 是服务账号邮箱client_email而不是数字形式的client_id。服务账号会模拟 Username 字段中指定的用户来发送邮件。这一点同样被源码强制执行SMTPOAuthService.assertConfigIsUsable()会校验 JWT Bearer 场景下 Username 必须存在且 Client Secret 必须包含-----BEGIN与PRIVATE KEY标记否则直接拒绝配置并返回明确的中文可读错误。常见问题排查Microsoft 365问题解决方法「Authentication unsuccessful」确认 service principal 已在 Exchange 中注册并拥有邮箱访问权限「AADSTS700016: Application not found」检查 Client ID 是否正确、应用是否存在于你的租户中「AADSTS7000215: Invalid client secret」重新生成 client secret——可能已过期「The mailbox is not enabled for this operation」运行Add-MailboxPermission授予邮箱访问权限Google Workspace问题解决方法「invalid_grant」确保域级委派配置正确且已生效最长需 24 小时「unauthorized_client」确认 Client ID 已在 Google Workspace 管理控制台完成授权「access_denied」检查https://mail.google.com/作用域是否已被授权「Domain policy has disabled third-party Drive apps」在 Google Workspace Admin Security API Controls 中启用 API 访问通用建议测试配置使用 OneUptime 的「Send Test Email」按钮验证配置是否生效。查看日志查阅 OneUptime 的日志以获取详细的错误信息。令牌缓存OneUptime 会缓存 OAuth 令牌并在过期前自动刷新。从源码看令牌缓存在 Redis 中跨容器共享缓存键基于配置元组configId、providerType、tokenUrl、clientId、clientSecret、scope、username经 HMAC-SHA256 派生避免缓存误命中导致令牌错发给其他配置。安全最佳实践定期轮换密钥设置日历提醒在 client secret 过期前完成轮换。使用专用服务账号/应用为 OneUptime 创建独立凭据避免与其他应用共享。遵循最小权限原则仅授予必要的最小权限Microsoft 用SMTP.SendAsAppGoogle 用mail.google.com作用域。监控使用情况定期审查邮件日志与 OAuth 应用登录记录留意异常活动。安全存储绝不将 client secret 提交到版本控制系统中。OneUptime 的数据模型对clientSecret、password使用TableColumnType.Password/VeryLongText列类型存储且读取权限仅对 Project Owner / Admin 开放见 ProjectSmtpConfig.ts 中的列访问控制声明。深入理解 OneUptime 的 SMTP 数据模型对于希望进一步了解实现细节的读者可以从以下几个文件入手ProjectSmtpConfig.tsSMTP 配置的核心数据模型定义了 hostname、port、fromEmail、fromName、secure、transportType、authType 以及全部 OAuth 字段并声明了基于角色的列级访问控制如ReadProjectSMTPConfig、EditProjectSMTPConfig权限与基于套餐的计费访问控制Growth 及以上计划可用。SMTPOAuthService.tsOAuth 令牌获取、Redis 缓存、JWT 签名、XOAUTH2 令牌生成的完整实现。MailService.ts根据认证类型创建 SMTP transporter、解析/api/notification/email/send请求并调用投递逻辑的服务端实现。EmailServer.ts定义调度侧与投递侧之间传递的 SMTP/OAuth 字段契约的接口类型。SchemaMigrations/1775900000000-AddGlobalSmtpOAuth.ts为全局 SMTP 配置增加 OAuth 字段的数据库迁移说明 OAuth 能力也覆盖运维级的全局邮件设置。将上述配置与源码理解结合你便能在 OneUptime 中稳定地通过 Microsoft 365 或 Google Workspace 以 OAuth 2.0 方式投递邮件同时规避企业环境中禁用基础认证所带来的发信难题。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考