文章目录概要QQ邮箱GmailOutlook1. 授权流程2. 关键配置3. Token 管理4. PKCE 支持5. 安全措施代理依赖SOCKS 代理IMAP 连接Azure Portal 配置指南1. 应用注册2. 配置身份验证Authentication3. 配置客户端密码Certificates secrets4. 配置 API 权限5. 配置支持的账户类型Manifest6. 当前应用信息7. 新环境部署检查清单8. 常见问题概要邮箱验证密码 邮件采集能力总结邮箱类型密码验证邮件采集说明QQ/Foxmail✅✅通过 IMAP 授权码163/126/yeah✅✅通过 IMAP 授权码Gmail✅✅通过应用专用密码采集服务需要配置代理Yahoo✅✅通过应用专用密码新浪✅✅通过 IMAP 授权码Outlook/Hotmail/Live❌❌微软禁用基本认证需 OAuth 2.0QQ邮箱QQ邮箱IMAP授权码获取步骤登录 mail.qq.com设置 → 账户 → POP3/IMAP/SMTP 服务开启IMAP/SMTP服务按提示发送短信生成16位授权码GmailGmail应用专用密码获取步骤登录 myaccount.google.com安全性 → 开启两步验证未开启需先开启直接访问 myaccount.google.com/apppasswords输入应用名称如IMAP客户端点击创建复制生成的16位应用专用密码将密码粘贴到此输入框OutlookMicrosoft 从 2022 年 10 月起已弃用 Outlook.com/Hotmail/Live 邮箱的 IMAP 基本身份验证技术实现使用 OAuth 2.0 Microsoft Graph API让用户主动授权前置条件开始实现前需要在 Azure Portal 注册应用内容较多步骤放在后面1. 授权流程用户点击授权连接 → 后端生成授权 URL含 PKCE code_challenge login_hint → 前端打开微软登录窗口 → 用户登录并授权 → 微软回调 /api/email/oauth/callback?codexxxstatexxx → 后端验证 state 用 codecode_verifierclient_secret 换取 token → 加密存储 refresh_token → 更新 oauth_statusAUTHORIZED → 返回 HTML 页面postMessage 通知父窗口2. 关键配置配置项说明email.outlook.oauth.client-idAzure AD 应用 Client IDemail.outlook.oauth.client-secretAzure AD 应用 Client Secretemail.outlook.oauth.tenant-idconsumers个人账号email.outlook.oauth.scopeoffline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.Reademail.outlook.oauth.redirect-uri各环境的回调地址3. Token 管理access_token 缓存Rediskeyoutlook:token:{emailId}TTL50minrefresh_token 存储数据库oauth_refresh_token字段AES-256-GCM 加密token 刷新采集时缓存未命中则用 refresh_token 换取新 access_tokentoken 轮换微软可能在刷新时返回新的 refresh_token需要更新数据库token 失效返回invalid_grant时标记oauth_statusEXPIRED4. PKCE 支持code_verifier43 字符 URL-safe 随机字符串code_challengeBASE64URL(SHA256(code_verifier))存储Redis与 state 一起存储keyoutlook:state:{state}TTL10min5. 安全措施state 参数防 CSRF一次性消费login_hint 引导用户登录正确账号client_secret 通过环境变量注入refresh_token 加密存储代理依赖SOCKS 代理IMAP 连接配置说明email.proxy.enabled是否启用代理email.proxy.host代理地址默认 127.0.0.1email.proxy.port代理端口默认 7890需要代理的场景Gmail IMAP 连接imap.gmail.com被墙其他被墙的邮箱服务器不需要代理的场景QQ/163/126 等国内邮箱Microsoft OAuth Token Endpointlogin.microsoftonline.com国内可直连Microsoft Graph APIgraph.microsoft.com国内可直连Azure Portal 配置指南1. 应用注册登录 Azure Portal进入Microsoft Entra ID原 Azure Active Directory→应用注册→新注册填写名称项目名称即可示例email-verify支持的账户类型任何组织目录中的账户和个人 Microsoft 账户AzureADandPersonalMicrosoftAccount重定向 URI暂时留空后续配置点击注册记录生成的Application (client) ID2. 配置身份验证Authentication左侧菜单 →Authentication (Preview)点击“ 添加重定向 URI”或“添加平台”→ 选择Web添加所有环境的重定向 URI根据实际项目填写即可http://localhost:XXXXXX/api/email/oauth/callback 开发环境 https://XXXXXX/api/email/oauth/callback 测试环境 https://XXXXXX/api/email/oauth/callback 生产环境不勾选隐式授权和混合流中的任何复选框使用标准 Authorization Code Flow点击配置保存3. 配置客户端密码Certificates secrets左侧菜单 →证书和密码点击“新客户端密码”填写描述email-oauth过期时间选24 个月点击添加立即复制生成的密码值只显示一次记录值Value即client-secret配置到OUTLOOK_OAUTH_CLIENT_SECRET环境变量机密 ID仅用于标识不需要配置到代码中4. 配置 API 权限左侧菜单 →API 权限点击“添加权限”→ 选择Microsoft Graph→委托的权限搜索并勾选以下权限IMAP.AccessAsUser.All— 邮箱 IMAP 读写访问Mail.ReadWrite— 邮件读写Graph API 邮件采集使用offline_access— 获取 refresh_tokenUser.Read— 读取用户基本信息默认已有点击添加权限注意IMAP.AccessAsUser.All和Mail.ReadWrite都添加确保兼容性。实际采集使用Mail.ReadWriteGraph API。5. 配置支持的账户类型Manifest左侧菜单 →清单Manifest确认以下字段值{signInAudience:AzureADandPersonalMicrosoftAccount,isFallbackPublicClient:true}如果signInAudience不是AzureADandPersonalMicrosoftAccount需要修改并保存6. 当前应用信息项目值应用名称email-verifyApplication (client) IDxxxx-xxxx-xxxx-xxxx-xxxxDirectory (tenant) ID使用consumers个人账号Client Secret 描述email-oauthClient Secret 过期2028/5/117. 新环境部署检查清单部署到新环境时需要完成以下步骤在 Azure Portal Authentication 中添加新环境的 redirect_uri确认 redirect_uri 使用 HTTPS生产环境必须确认 redirect_uri 路径与后端 context-path 一致通过环境变量注入OUTLOOK_OAUTH_CLIENT_ID通过环境变量注入OUTLOOK_OAUTH_CLIENT_SECRET敏感信息通过环境变量注入OUTLOOK_OAUTH_REDIRECT_URI确认 Redis 可用state 存储 token 缓存确认数据库已执行迁移脚本OAuth 字段确认网络能访问login.microsoftonline.com和graph.microsoft.com8. 常见问题错误原因解决方案invalid_request: redirect_uri is not validredirect_uri 未在 Azure Portal 注册在 Authentication 中添加AADSTS70002: must include client_secret应用需要 client_secret在证书和密码中生成并配置AADSTS70011: invalid_scopescope 格式错误或权限未添加在 API 权限中添加对应权限AADSTS9001023: grant type not supportedROPC 不支持 /common endpointtenant-id 使用consumersunsupported_grant_type个人账号不支持 ROPC正常行为引导用户使用 OAuth 授权401 body 为空Java HttpURLConnection streaming 问题代码已使用原生 HttpsURLConnection 绕过
