跳到主要内容

配置 Outlook/Microsoft 365 OAuth 认证

本指南将引导您创建用于 Outlook/Microsoft 365 OAuth 认证的 Microsoft Azure 应用。OAuth 相比传统密码认证更安全。

前置条件​

  • Microsoft 账户（个人或 Microsoft 365/Office 365）
  • 可访问 Azure Portal
  • Perfex CRM 安装 URL（用于配置 redirect URI）
信息

对于 Microsoft 365 组织，可能需要管理员批准。

分步配置​

步骤 1：在 Azure Portal 注册应用​

  1. 访问 Azure Portal
  2. 使用 Microsoft 账户登录
  3. 进入 "Azure Active Directory"（或搜索）
  4. 在左侧菜单点击 "App registrations"
  5. 点击 "+ New registration"
  6. 填写应用信息：
    • Name：输入名称（如 "Perfex CRM Mailbox"）
    • Supported account types：选择 "Accounts in any organizational directory and personal Microsoft accounts" 以获得最大兼容性
    • Redirect URI：
      • Platform：Web
      • URI：https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
      • 将 your-domain.com 替换为实际 Perfex CRM 域名
  7. 点击 "Register"

步骤 2：配置 API 权限​

  1. 在应用注册中，点击左侧 "API permissions"
  2. 点击 "+ Add a permission"
  3. 选择 "Microsoft Graph"
  4. 选择 "Delegated permissions"
  5. 添加以下权限：
    • Mail.Read - 读取所有邮箱中的邮件
    • Mail.ReadWrite - 读取和写入所有邮箱中的邮件
    • Mail.Send - 以用户身份发送邮件
    • offline_access - 保持对已授权数据的访问（用于 token 刷新）
  6. 点击 "Add permissions"
  7. 重要：若看到 "Grant admin consent for [Your Organization]" 按钮，请点击
注意

组织账户需要此步骤，且需管理员权限。

步骤 3：创建 Client Secret​

  1. 在应用注册中，点击左侧 "Certificates & secrets"
  2. 点击 "+ New client secret"
  3. 输入描述（如 "Perfex Mailbox Secret"）
  4. 选择有效期：24 个月（生产环境推荐）
  5. 点击 "Add"
  6. 重要：立即复制 Value（之后无法再次查看），即 Client Secret

步骤 4：获取 Application (Client) ID​

  1. 在应用注册中进入 "Overview"
  2. 复制 Application (client) ID，即 Client ID

步骤 5：验证 Redirect URI​

  1. 在应用注册中，点击左侧 "Authentication"
  2. 在 "Redirect URIs" 下确认 redirect URI 已列出：
https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  1. 若未列出，点击 "+ Add a platform" > "Web" 并添加
  2. 在 "Implicit grant and hybrid flows" 下，确保勾选 "Access tokens"（如有）
  3. 点击 "Save"

步骤 6：在 Perfex CRM 中配置​

  1. 进入 Perfex CRM 管理后台
  2. 进入 Mailbox > Configuration
  3. 选择 "OAuth2" 认证方式
  4. 选择 "Outlook" 提供商
  5. 输入 Client ID（Azure 中的 Application ID）
  6. 输入 Client Secret（已复制的密钥值）
  7. Microsoft 365 组织：输入 Tenant ID（在 Azure AD > Overview 中）。个人 Microsoft 账户可留空。
  8. 点击 "Save Configuration"
  9. 点击 "Connect Outlook" 按钮
  10. 在 Microsoft 弹出窗口中授权应用
  11. 应显示连接成功的消息

重要限制与注意事项​

Microsoft Azure 应用限制​

These limitations are imposed by Microsoft, not by our software.

  1. 管理员同意要求 - 组织账户（Microsoft 365/Office 365）需要 管理员同意 才可授予某些权限。管理员必须在用户使用前批准应用。

  2. 账户类型限制：

    • "Accounts in this organizational directory only" - 仅您组织内的用户
    • "Accounts in any organizational directory" - 任意 Microsoft 365 组织的用户
    • "Accounts in any organizational directory and personal Microsoft accounts" - 最大兼容性
    • "Personal Microsoft accounts only" - 仅个人 @outlook.com、@hotmail.com 账户

  3. Tenant ID 要求 - 组织账户需要 Tenant ID 才能正确认证。个人账户可留空。

应用验证与发布​

  • 未验证应用 可立即用于个人账户，但可能向用户显示警告。
  • 已验证应用 需提交至 Microsoft App Store（可选），体验更好（无警告）。
  • 管理员同意流程 - 组织账户需由管理员授权。管理员可见应用请求的权限。

Token 刷新​

模块会自动处理 token 刷新：

  • Refresh tokens：通过 offline_access 权限自动获取
  • Token 过期：access token 通常 1 小时，refresh token 通常 90 天
  • 自动刷新：模块会在过期前自动刷新 token

多租户与单租户​

  • 多租户：任意 Microsoft 账户均可使用（每个组织需分别获得管理员同意）
  • 单租户：仅您组织内可使用

备注​

  • redirect URI 必须与 Azure Portal 中配置的完全一致
  • 妥善保管 Client Secret，切勿公开
  • 若更换域名，请在 Azure Portal 中更新 redirect URI
  • 组织账户需确保已获得管理员同意
  • Tenant ID 仅 Microsoft 365/Office 365 账户需要
  • OAuth 流程由 Microsoft 处理，模块仅负责发起请求并接收回调

故障排除​

"AADSTS50011: Redirect URI mismatch" 错误：

  • 确认 Azure Portal 中的 redirect URI 完全一致：https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  • 检查尾斜杠及 HTTP/HTTPS 是否一致
  • 确认 URI 已列在 "Web" 平台类型下

"Admin consent required" 错误：

  • 组织账户属预期行为（Microsoft 政策）
  • 联系 Microsoft 365 管理员授予同意
  • 管理员可在 Azure Portal > Enterprise applications 中授权

"Invalid client secret" 错误：

  • Client secret 会过期，需在 Azure Portal 中创建新的
  • 确认复制的是 "Value"（非 Secret ID）
  • 检查 secret 是否已过期

"AADSTS700016: Application not found" 错误：

  • 确认 Client ID 正确
  • 确保使用的是 Application (client) ID，而非 Object ID
  • 确认应用注册存在于正确的 Azure AD tenant 中

"Token refresh failed" 错误：

  • 确认已授予 offline_access 权限
  • 验证组织账户是否已获得管理员同意
  • 检查 client secret 是否已过期

延伸阅读​

信息

管理员同意要求、账户类型限制及 token 政策为 Microsoft 对 Azure 应用的安全策略，并非本软件设定。