自托管 n8n 如何连接 Outlook
在 Microsoft Entra 中注册应用,配置正确的 OAuth 回调 URL,并了解客户端密钥过期为何会导致 Outlook 工作流中断。
如何将 Outlook 连接到自托管 n8n
要将 Outlook 连接到自托管 n8n,请先在 Microsoft Entra ID 中注册应用。然后,将 n8n 实例显示的 OAuth 回调 URL 添加到该应用,并将应用的客户端 ID 和客户端密钥粘贴到 n8n 凭据中。n8n Cloud 用户无需执行这些操作,因为 Cloud 不要求用户提供连接详细信息。在您自己的服务器上,应用注册归您所有,因此其设置和会过期的密钥也由您负责管理。
先介绍几个术语。OAuth(Open Authorization)是一种登录流程,允许 n8n 代表您操作邮箱,而无需存储您的密码。Microsoft Entra ID 是 Microsoft 的身份服务,前身为 Azure Active Directory。Microsoft Graph 是 n8n 用于读取和发送 Outlook 邮件的 API。UPN(user principal name)是 Microsoft 365 账户的登录名,格式类似电子邮件地址。
大多数失败都由两个设置引起:重定向 URI 和账户类型。几个月后还可能出现第三个问题,即客户端密钥过期。本指南将涵盖这些问题,然后构建一个用于回复新邮件的小型工作流。
开始前的准备工作
- 一个可通过 HTTPS 在真实域名上访问的自托管 n8n 实例。使用 Docker 和 HTTPS 在 VPS 上运行 n8n介绍了具体配置步骤。
- 一个 Microsoft 账户。个人 Outlook.com 账户和 Microsoft 365 租户中的工作或学校账户均可使用。
- 对于工作租户:您需要拥有自行同意应用的权限,或者由管理员代为授予同意。
为什么回调 URL 取决于公网 URL
OAuth 登录结束时,Microsoft 会让浏览器返回 n8n,并附带一次性代码。这个返回地址就是回调 URL。n8n 会根据它认为的自身公网 URL 生成该地址。该地址由三部分组成:实例基础 URL、REST 端点路径段和 /oauth2-credential/callback。REST 路径段来自 N8N_ENDPOINT_REST,其默认值为 rest,因此默认安装的路径是 /rest/oauth2-credential/callback。修改该变量后,路径也会随之改变。路径前面的基础 URL 来自您的配置。
如果设置了 N8N_EDITOR_BASE_URL,n8n 会使用它。如果未设置,n8n 会回退到 webhook URL。如果仍未设置,n8n 会根据 N8N_PROTOCOL、N8N_HOST、N8N_PORT 和 N8N_PATH 生成地址;这些变量的默认值分别为 http、localhost、5678 和 /。
最后一种回退方式最容易导致问题。n8n 位于反向代理后面时,无法看到代理对外提供服务的域名。因此,未设置 URL 变量的实例会输出 http://localhost:5678/rest/oauth2-credential/callback。如果您在 Entra 中注册了真实域名,但 n8n 发送的是 localhost,登录会失败,并显示以下错误:
AADSTS50011: The redirect URI 'http://localhost:5678/rest/oauth2-credential/callback' specified in the request does not match the redirect URIs configured for the applicationMicrosoft 会逐字符比较请求中的 URI 和已注册的 URI 列表。请在 compose 文件中显式设置公网 URL:
services:
n8n:
environment:
- N8N_HOST=n8n.example.com
- N8N_PROTOCOL=https
- N8N_EDITOR_BASE_URL=https://n8n.example.com
- N8N_WEBHOOK_URL=https://n8n.example.com/
- N8N_PROXY_HOPS=1该变量名称最近发生了变化。从 n8n 2.35.0 开始,webhook 变量为 N8N_WEBHOOK_URL。旧名称 WEBHOOK_URL 仍作为别名有效,但 n8n 会在启动时记录弃用警告(截至 October 2026)。如果使用较旧的版本,请使用 WEBHOOK_URL。N8N_PROXY_HOPS=1 告诉 n8n,它运行在一个反向代理后面,因此可以信任代理发送的 X-Forwarded-For、X-Forwarded-Host 和 X-Forwarded-Proto 标头。
docker compose up -d
docker compose exec n8n env | grep -E 'N8N_EDITOR_BASE_URL|WEBHOOK_URL'up -d 会在环境发生变化后重新创建容器。第二条命令应输出这两个变量及您的 https 域名。如果 compose 服务使用了其他名称,请将第二条命令中的 n8n 替换为实际名称。n8n 只会在启动时读取这些值,因此编辑文件后,必须重启容器才会生效。
现在执行关键检查。在 n8n 中创建新凭据,并选择 Microsoft Outlook OAuth2 API。表单中会显示 OAuth Redirect URL 字段。该字段必须以 https:// 和您的域名开头。如果仍显示 localhost,请先修复这些变量,因为后续每一步都会复制此值。
在 Microsoft Entra ID 中注册应用
在一个选项卡中保持 n8n 凭据表单打开。然后在另一个选项卡中执行以下步骤。
- 打开应用注册门户,并使用将拥有该应用的 Microsoft 帐户登录。
- 选择 New registration,然后为应用设置名称,例如
n8n。 - 在支持的帐户类型下,选择 Accounts in any organizational directory (Any Azure AD directory - Multi-tenant) and personal Microsoft accounts。这是 n8n 文档使用的名称。较新版本的门户可能会使用 “Microsoft Entra ID tenant” 替代 “Azure AD directory”。请选择涵盖任意组织帐户和个人帐户的选项。
- 在 Redirect URI 下,选择 Select a platform,然后选择 Web,并粘贴 n8n 中的 OAuth Redirect URL。
- 选择 Register,然后从概览页复制 Application (client) ID,将其粘贴到 n8n 凭据的 Client ID 字段中。
帐户类型很重要,因为 n8n 的 Microsoft 凭据通过 login.microsoftonline.com/common 端点登录。Microsoft 仅允许多租户应用使用此端点。注册单租户应用后,登录会失败,并显示以下错误:
AADSTS50194: Application '<client id>'(n8n) is not configured as a multi-tenant application. Usage of the /common endpoint is not supported for such applications created after '10/15/2018'.平台类型同样重要。n8n 在服务器上使用 client secret 将代码交换为令牌,这正是 Web 平台的用途。如果将 URI 注册在 Single-page application 下,代码交换会因 AADSTS9002327 而失败,因为 Microsoft 只允许此客户端类型通过浏览器 JavaScript 兑换令牌。
创建客户端密钥并规划其到期时间
- 在应用注册中,打开左侧菜单的 Certificates & secrets。
- 在 Client secrets 下,选择 New client secret。
- 添加描述,例如
n8n credential,并选择到期时间。 - 选择 Add,然后将 Value 列中的值复制到 n8n 凭据的 Client Secret 字段。
复制 Value,不要复制旁边的 Secret ID。门户只显示一次该值。离开此页面后,该值将永久隐藏,您必须创建新的密钥。如果误将 Secret ID 粘贴进去,登录会因 AADSTS7000215: Invalid client secret provided 失败。
仔细阅读到期时间选项。门户提供预设有效期和 Custom 选项。Microsoft 将每个客户端密钥的有效期限制为 24 个月,并建议设置为少于 12 个月。任何密钥都不会永久有效。
以下是到期时间重要的原因。n8n 会为您的邮箱存储刷新令牌。每次短期访问令牌过期时,n8n 都会将客户端 ID、密钥和刷新令牌发送给 Microsoft,以获取新的访问令牌。密钥到期后,该请求会因 AADSTS7000222: The provided client secret keys for app '<client id>' are expired 失败。此后,使用该凭据的每个节点都会失败,包括每次轮询时运行的触发器。到期前不会收到任何提醒,因此请在创建密钥时将到期日期添加到日历中。
在密钥到期前轮换:
- 在旧密钥仍有效时添加新的客户端密钥。一个应用可以同时保存多个密钥。
- 将新值粘贴到凭据的 Client Secret 字段中,然后保存。
- 手动运行一个 Outlook 节点,确认其执行成功。如果 n8n 要求您重新连接,请按要求操作。
- 在 Certificates & secrets 中删除旧密钥。
连接凭据及其请求的权限范围
填写客户端 ID 和密钥后,在凭据中选择连接按钮。系统会打开 Microsoft 登录窗口,并列出 n8n 请求的权限。选择接受后,窗口会关闭,凭据也就连接完成。
Microsoft Outlook 凭据请求以下权限范围(权限)。这些权限列在 n8n 文档和凭据源代码中:
openid offline_access Contacts.Read Contacts.ReadWrite Calendars.Read
Calendars.Read.Shared Calendars.ReadWrite Mail.ReadWrite Mail.ReadWrite.Shared
Mail.Send Mail.Send.Shared MailboxSettings.Readoffline_access 是向 n8n 提供刷新令牌的权限范围,因此连接的有效时间可以超过一小时。.Shared 权限范围允许 n8n 使用您的帐户已经可以打开的邮箱。它们本身不会授予任何访问权限。对于正常登录,您不需要在 Entra 中添加这些权限,因为凭据会在登录时请求它们。关闭凭据的自定义权限范围选项,不要再请求其他权限。
工作租户何时需要管理员同意?
n8n 文档说明了这一要求:在使用 Microsoft Entra 的组织中,必须为用户启用允许其代表自己同意应用访问公司数据的设置。如果未启用,则必须由管理员授予同意。许多租户会限制用户同意。登录窗口会显示 需要管理员批准,而不是权限列表,此时即可确认存在此限制。
最简便的修复方式是仅保留 n8n 请求的权限。管理员打开应用注册,进入 API permissions,然后添加上方列表中的委托 Microsoft Graph 权限。openid 和 offline_access 位于权限选择器的 OpenId permissions 下。然后,管理员选择 Grant admin consent for 该租户。完成后,用户即可正常连接凭据。
个人 Outlook.com 帐户不会看到此步骤,因为在用户与自己的邮箱之间没有租户管理员。
如何通过 UPN 读取共享收件箱
要自动处理 support@example.com 这样的共享邮箱,请在凭据中启用 Use Shared Inbox,并输入目标邮箱的 UPN 或 ID。您仍使用自己的账号登录。随后,n8n 会在 Graph 中将请求发送到 /users/<UPN>/,而不是 /me/。
这会带来两个结果。首先,您的账号必须已获得该邮箱的访问权限。Exchange 管理员会将此权限授予邮箱。否则,Graph 会返回 ErrorAccessDenied 以及消息 Access is denied. Check credentials and try again.。其次,UPN 保存在凭据中,因此一个凭据只能读取一个邮箱。请为共享收件箱创建第二个凭据,并保留个人凭据不变。
构建工作流:自动回复新邮件
此工作流会回复收件箱中的每封新邮件,然后将其标记为已读。使用3个节点。
- Microsoft Outlook Trigger。选择凭据。将 Trigger On 设置为 Message Received,并将 Output 保持为 Simplified。在 Filters 下,将 Folders to Include 设置为 Inbox,并将 Read Status 保持为 unread messages,这是默认值。在测试期间,还应将 Sender 设置为您可以控制的地址。
- Microsoft Outlook,Resource 设置为 Message,Operation 设置为 Reply。将 Message ID 设置为
{{ $json.id }}。在 Message 中输入回复内容。启用 Reply to Sender Only,因为该选项默认关闭;关闭时,系统会向原始邮件的所有收件人回复。 - Microsoft Outlook,Resource 设置为 Message,Operation 设置为 Update。将 Message ID 设置为
{{ $('Microsoft Outlook Trigger').item.json.id }}。在 Update Fields 下添加 Is Read,并将其启用。
第三个节点按名称指向触发器,因为在回复节点之后,$json 保存的是回复的输出,不再保存原始邮件。如果您重命名了触发器节点,请在表达式中使用您设置的名称。
要进行测试,请从测试地址发送一封邮件,然后在触发器上使用 Fetch Test Event。在手动模式下,触发器会获取最新的匹配邮件,因此您无需等待即可逐步测试回复。检查测试收件箱中是否收到回复,并确认原始邮件在 Outlook 中已显示为已读。然后激活工作流,使触发器按计划运行。只有确认回复内容正确后,才移除 Sender 过滤器。自动回复如果发送给另一个自动回复程序(例如外出自动回复),可能会形成邮件循环。
Outlook 触发器如何检查新邮件?
该触发器通过轮询检查邮件。Microsoft 不会主动向它推送邮件。其 Poll Times 设置默认为每分钟检查一次。每次轮询时,n8n 会向 Graph 请求 receivedDateTime 在上次检查时间之后或等于该时间、且早于当前时间的邮件。然后,它会将当前时间保存为下一个时间窗口的起点。首次激活时,时间窗口从激活时刻开始,因此邮箱中已有的邮件不会触发该触发器。
如果未设置 Folders to Include,触发器会查询 Graph 的 /messages 端点,该端点涵盖所有文件夹,包括“已发送邮件”。因此,上面的工作流将范围限制为 Inbox。触发器也不会保存已处理邮件的 ID 列表。n8n 节点本身的说明指出,每封邮件必须且只能处理一次,并建议将邮件标记为已读、移动到某个文件夹,或记录其 ID。Update 节点执行了第一种操作,未读邮件筛选器会跳过已处理的邮件。
如果每分钟检查一次过于频繁,可以选择每小时或每天检查一次。这些计划使用实例的时区运行;n8n 如何为计划解析时区会说明服务器与工作流使用不同设置时,哪个设置优先。
故障模式及对应的错误信息
AADSTS50011,重定向 URI 不匹配:n8n 中的 OAuth Redirect URL 与 Entra 中的 Web URI 不一致。修正 URL 变量,重启,然后重新复制 URL。AADSTS50194:应用是单租户应用。在 Authentication 下更改支持的帐户类型,或注册新应用。AADSTS7000215:粘贴了 Secret ID,而不是密钥 Value。AADSTS7000222:密钥已过期。创建新密钥,然后粘贴其值。- 需要管理员批准:租户禁止用户同意。必须由管理员授予同意。
- 共享收件箱出现
ErrorAccessDenied:您的帐户无权访问 Exchange 中的该邮箱。
Google 也使用相同的 OAuth 模式。将 Gmail 连接到自行托管的 n8n 使用 Google Cloud OAuth 客户端代替 Entra 应用,并使用相同变量中的回调 URL。本指南不需要付费计划,n8n Community 与 Enterprise 的区别涉及团队功能,而不是可使用的节点。
FAQ
在自托管 n8n 中,应在 Microsoft Entra 注册什么重定向 URI?
在 Web 平台下注册 n8n 凭据表单显示的完整 OAuth 重定向 URL。默认安装时,该 URL 以 /rest/oauth2-credential/callback 结尾。如果修改了 N8N_ENDPOINT_REST,则使用您的值替换 rest 部分。如果 URL 以 http://localhost:5678 开头,说明 n8n 不知道其公网地址。将 N8N_EDITOR_BASE_URL 和 webhook URL 变量设置为您的 HTTPS 域名,重启容器,然后重新复制该 URL。
为什么我的 n8n Outlook 凭据在几个月后停止工作?
最可能的原因是客户端密钥已过期。Microsoft 将客户端密钥的有效期限制为 24 个月。密钥过期后,n8n 无法再刷新访问令牌。错误信息为 AADSTS7000222: The provided client secret keys for app ... are expired。在 Certificates & secrets 中创建新密钥,将其值粘贴到凭据中,然后删除旧密钥。
n8n 可以读取 Microsoft 365 中的共享邮箱吗?
可以。在 Microsoft Outlook 凭据中启用 Use Shared Inbox,然后输入共享邮箱的 UPN。您仍以自己的帐户登录,因此该帐户必须已在 Exchange 中获得该邮箱的访问权限,否则 Graph 会返回 ErrorAccessDenied。每个邮箱使用单独的凭据,因为 UPN 会存储在凭据中。
n8n Outlook 触发器多久检查一次新邮件?
它按照 Poll Times 中设置的计划轮询,默认每分钟检查一次。每次轮询都会向 Microsoft Graph 请求自上次检查以来收到的邮件。启用工作流之前收到的邮件不会触发该工作流。触发器不会记录已处理的邮件,因此处理后请将每封邮件标记为已读或移动到其他位置。