文章目录概要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 绕过
Outlook授权流程、Gmail QQ邮箱 IMAP 授权码的获取方式
文章目录概要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 绕过
