Outlook授权流程、Gmail QQ邮箱 IMAP 授权码的获取方式

概要

邮箱验证密码 邮件采集能力总结

QQ邮箱

QQ邮箱IMAP授权码获取步骤：

1. 登录 mail.qq.com
2. 设置 → 账户 → POP3/IMAP/SMTP 服务
3. 开启"IMAP/SMTP服务"
4. 按提示发送短信生成16位授权码

Gmail

Gmail应用专用密码获取步骤：

1. 登录 myaccount.google.com
2. 安全性 → 开启"两步验证"（未开启需先开启）
3. 直接访问 myaccount.google.com/apppasswords
4. 输入应用名称如"IMAP客户端"，点击"创建"
5. 复制生成的16位应用专用密码
6. 将密码粘贴到此输入框

Outlook

Microsoft 从 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?code=xxx&state=xxx → 后端验证 state + 用 code+code_verifier+client_secret 换取 token → 加密存储 refresh_token → 更新 oauth_status=AUTHORIZED → 返回 HTML 页面，postMessage 通知父窗口

2. 关键配置

3. Token 管理

• access_token 缓存：Redis，key=outlook:token:{emailId}，TTL=50min
• refresh_token 存储：数据库oauth_refresh_token字段，AES-256-GCM 加密
• token 刷新：采集时缓存未命中则用 refresh_token 换取新 access_token
• token 轮换：微软可能在刷新时返回新的 refresh_token，需要更新数据库
• token 失效：返回invalid_grant时标记oauth_status=EXPIRED

4. PKCE 支持

• code_verifier：43 字符 URL-safe 随机字符串
• code_challenge：BASE64URL(SHA256(code_verifier))
• 存储：Redis，与 state 一起存储，key=outlook:state:{state}，TTL=10min

5. 安全措施

• state 参数防 CSRF（一次性消费）
• login_hint 引导用户登录正确账号
• client_secret 通过环境变量注入
• refresh_token 加密存储

代理依赖

SOCKS 代理（IMAP 连接）

需要代理的场景：

• Gmail IMAP 连接（imap.gmail.com被墙）
• 其他被墙的邮箱服务器

不需要代理的场景：

• QQ/163/126 等国内邮箱
• Microsoft OAuth Token Endpoint（login.microsoftonline.com国内可直连）
• Microsoft Graph API（graph.microsoft.com国内可直连）

Azure Portal 配置指南

1. 应用注册

1. 登录 Azure Portal
2. 进入Microsoft Entra ID（原 Azure Active Directory）→应用注册→新注册
3. 填写：
   • 名称：项目名称即可，示例：email-verify
   • 支持的账户类型：任何组织目录中的账户和个人 Microsoft 账户（AzureADandPersonalMicrosoftAccount）
   • 重定向 URI：暂时留空（后续配置）
4. 点击"注册"，记录生成的Application (client) ID

2. 配置身份验证（Authentication）

1. 左侧菜单 →Authentication (Preview)
2. 点击“+ 添加重定向 URI”或“添加平台”→ 选择Web
3. 添加所有环境的重定向 URI（根据实际项目填写即可）：

http://localhost:XXXXXX/api/email/oauth/callback （开发环境） https://XXXXXX/api/email/oauth/callback （测试环境） https://XXXXXX/api/email/oauth/callback （生产环境）

4. 不勾选"隐式授权和混合流"中的任何复选框（使用标准 Authorization Code Flow）
5. 点击"配置"保存
   

3. 配置客户端密码（Certificates & secrets）

1. 左侧菜单 →证书和密码
2. 点击“新客户端密码”
3. 填写描述：email-oauth，过期时间选24 个月
4. 点击"添加"
5. 立即复制生成的密码值（只显示一次！）
6. 记录：
   • 值（Value）：即client-secret，配置到OUTLOOK_OAUTH_CLIENT_SECRET环境变量
   • 机密 ID：仅用于标识，不需要配置到代码中
     

4. 配置 API 权限

1. 左侧菜单 →API 权限
2. 点击“添加权限”→ 选择Microsoft Graph→委托的权限
3. 搜索并勾选以下权限：
   • IMAP.AccessAsUser.All— 邮箱 IMAP 读写访问
   • Mail.ReadWrite— 邮件读写（Graph API 邮件采集使用）
   • offline_access— 获取 refresh_token
   • User.Read— 读取用户基本信息（默认已有）
4. 点击"添加权限"

注意：IMAP.AccessAsUser.All和Mail.ReadWrite都添加，确保兼容性。实际采集使用Mail.ReadWrite（Graph API）。

5. 配置支持的账户类型（Manifest）

1. 左侧菜单 →清单（Manifest）
2. 确认以下字段值：

{"signInAudience":"AzureADandPersonalMicrosoftAccount","isFallbackPublicClient":true}

3. 如果signInAudience不是AzureADandPersonalMicrosoftAccount，需要修改并保存
   

6. 当前应用信息

7. 新环境部署检查清单

部署到新环境时，需要完成以下步骤：

• 在 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.com

8. 常见问题