---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 为 OpenConnector 创建 Microsoft OAuth app
description: 为 Outlook、OneDrive、Excel 等 OOMOL OpenConnector Microsoft Graph
  provider 注册 Microsoft Entra application。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/openconnector-microsoft-oauth-app/
markdown_url: https://oomol.com/zh-cn/docs/openconnector-microsoft-oauth-app.md
---

# 为 OpenConnector 创建 Microsoft OAuth app

当 OpenConnector 需要连接 Outlook、OneDrive 或 Excel 等 Microsoft Graph provider 时，使用 Microsoft Entra app registration。

## OpenConnector services

| Service ID | Provider | Extra client field |
| --- | --- | --- |
| `outlook` | Outlook | `tenant` |
| `one_drive` | OneDrive | `tenant` |
| `excel` | Excel | `tenant` |

`tenant` 是 authorization 和 token URL 中使用的 Microsoft identity platform tenant segment。常见值包括 `common`、`organizations`、`consumers` 或具体 tenant ID。

## 前置条件

- 一个正在运行的 OpenConnector runtime。
- 可以访问 Microsoft Entra admin center 或 Azure app registrations。
- 有权限注册 app 和创建 client secret。
- 用户在浏览器中打开的 OpenConnector origin，例如 `http://localhost:3000` 或 `https://connect.example.com`。

## 第 1 步：确定 OpenConnector callback URL

在 OpenConnector origin 后拼接 `/oauth/callback`，得到 callback URL。本地测试使用 `http://localhost:3000/oauth/callback`。公开部署时，请先设置 `OOMOL_CONNECT_ORIGIN`，重启 OpenConnector 后使用公开 callback URL，例如 `https://connect.example.com/oauth/callback`。

## 第 2 步：注册 Microsoft app

在 [Microsoft Entra admin center](https://entra.microsoft.com/) 中：

1. 打开 **App registrations**。
2. 创建新的 registration。
3. 选择适合目标用户的 supported account type。
4. 添加一个 **Web** redirect URI，值为 OpenConnector 的准确 callback URL。
5. 注册 app。
6. 打开 **Certificates & secrets**，创建 client secret。
7. 打开 **API permissions**，添加 OpenConnector service 需要的 delegated Microsoft Graph permissions。

Microsoft 官方文档见 [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。Microsoft 授权码流程要求 auth request 里的 redirect URI 匹配已注册 redirect URI。

## 第 3 步：复制 client values

| Microsoft 字段 | OpenConnector 字段 |
| --- | --- |
| Application client ID | `clientId` |
| Client secret value | `clientSecret` |
| Tenant segment | `extra.tenant` |

创建 client secret 后立刻复制 secret value。Microsoft 后续不会再次显示完整 secret value。

## 第 4 步：在 OpenConnector 中保存 client

OpenConnector 的 Microsoft providers 需要额外的 `tenant` 值。请使用能在 OAuth client 表单中展示 `tenant` 字段的 OpenConnector 控制台版本，再按本文继续配置。

1. 打开 OpenConnector Web 控制台，例如 `http://localhost:3000`。
2. 打开 **Providers**，选择 **Outlook**、**OneDrive** 或 **Excel**。
3. 点击 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 粘贴 Microsoft application client ID 和 client secret value。
5. 在 **Tenant** 中填写 `common`、`organizations`、`consumers` 或你的 tenant ID。
6. 点击 **Save OAuth Client**。

配置 `one_drive` 或 `excel` 时，在对应 provider 页面重复这些步骤。

## 第 5 步：连接并测试

保存 OAuth client config 后，在 Microsoft provider 页面点击 **Connect**。登录 Microsoft 账号，批准 consent，回到 OpenConnector，并确认 provider 页面显示账号已连接。

运行 Microsoft Graph action 前，先查看控制台里的 action 详情。如果你的 catalog 版本没有 `outlook.list_messages`，请选择该 provider 当前展示的其他读取 action。

## 排查建议

| 现象 | 检查项 |
| --- | --- |
| Microsoft 提示 redirect URI 无效 | 在 app registration 中添加准确的 `<openconnector-origin>/oauth/callback` URL，平台类型选择 Web。 |
| 目标用户无法登录 | 检查 app 的 supported account type，以及 OpenConnector 保存的 `tenant` 值。 |
| 需要 admin consent | 某些 Microsoft Graph permissions 或 tenant policy 要求管理员同意，请让 tenant admin 审核 app。 |
| Token request 失败 | 确认保存了当前 client secret value；secret ID 只用于标识这条 secret 记录。 |
| Action 提示权限不足 | 添加所需 delegated API permissions，完成 consent，然后重新连接 Microsoft 账号。 |