通过

发布需要管理员同意才能Microsoft Graph 范围的加载项

本文介绍如何将更新发布到 Office 外接程序以使用 Microsoft Graph 范围并需要管理员同意。 如果你已将 Outlook 加载项从旧版Exchange Online令牌移动到使用Microsoft身份验证库 (MSAL) 与嵌套应用身份验证 (NAA) ，以及使用 Microsoft Graph API Entra ID令牌，则这种情况很常见。

若要发布更新，需要考虑三件事。

  1. 如何将外接程序代码中所做的更改部署到 Web 服务器。
  2. 如何获取Microsoft Graph 范围的管理员同意。
  3. 如何在清单中部署更新。

将更新部署到外接程序代码

更新并测试加载项代码后，需要将它们部署到 Web 服务器。 遵循自己的更新过程 (，例如过渡和生产) 。 部署后，外接程序的所有用户都将看到更改并开始使用更新的外接程序代码。 管理员或用户无需执行任何作即可查看更新。

加载项使用的任何Microsoft Graph 范围都需要用户或租户管理员的同意。 如果管理员不同意，当加载项通过 MSAL 请求访问令牌时，系统会提示用户提供同意。 为了获得最佳用户体验，请完全避免提示用户同意。 相反，请要求管理员为整个租户提供同意。

有两种方法可以获取管理员同意：使用管理员同意 URI 或使用统一清单。

可以通过提供管理员同意 URI 来获取管理员同意。 它提供管理员可选择的链接。 一个对话框提示他们使用管理员凭据登录，并同意加载项所需的 Microsoft Graph 范围。

若要构造管理员 URI，请使用以下模式。

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}

其中：

  • client_id：应用注册的 ID。
  • scope：每个范围 (（例如 Microsoft Graph 范围) ）都需要管理员同意，使用空格作为分隔符。 由于 Microsoft 身份验证库 (MSAL) 始终请求 ID 和刷新令牌，因此应始终包括 openid、 profile和 offline_access 范围。 MSAL 默认会请求这些请求，即使加载项不请求它们。
  • redirect_uri：同意完成时的重定向页面。 管理员同意后，Microsoft 标识平台将重定向到此页面。 重定向页面将按照Microsoft 标识平台管理员同意中指定的格式发送成功或失败 JSON 消息。 在页面上，你可以向管理员指示同意状态，并提供有关加载项的详细信息或后续步骤。

重要

必须将重定向页添加到单页应用程序列表， (SPA) 重定向以及 brk-multihub 重定向，否则管理员同意 URI 将失败。

以下管理员 URI 示例演示如何指定 openid、profile、 user.readoffline_access和 files.read 范围，以及如何重定向到 Web 服务器上名为 consentRedirect.html的页面。

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=63e62b68-c5c7-48f9-82bf-8c41d5637b49&scope=offline_access openid profile user.read files.read&redirect_uri=https://localhost:3000/consentRedirect.html

注意

如果在范围参数中省略资源标识符，则假定资源Microsoft Graph。 例如，User.Read 等同于 https://graph.microsoft.com/User.Read。

部署外接程序时，还可以作为部署工作流的自动一部分获得管理员同意。 为此，请将 webApplicationInfo 属性添加到统一清单。 然后，管理员通过集中部署或从更新通过 Microsoft AppSource 部署更新的清单。 当管理员部署更新的清单时，系统会自动提示他们同意加载项所需的范围。 如果他们不同意，则不会部署更新的加载项。

将 Graph 范围添加到应用注册

当管理员部署加载项的更新清单时，同意过程将读取应用注册，其范围要求管理员同意。 请务必使用以下步骤添加外接程序所需的所有权限。

  1. 登录到 Azure 门户 并打开应用注册。

  2. 在左窗格中，选择“ API 权限”。

    “API 权限”窗格。

    “ API 权限 ”窗格随即打开。

  3. 选择“添加权限”。

    在“API 权限”窗格中添加权限。

    此时会打开 “请求 API 权限 ”窗格。

  4. 选择 Microsoft Graph。

    带有“Microsoft图形”按钮的“请求 API 权限”窗格。

  5. 选择“委托的权限”。

    具有委托权限按钮的“请求 API 权限”窗格。

  6. 在 “选择权限” 搜索框中，搜索外接程序所需的权限。 例如，对于 Outlook 外接程序，可以使用 profile、 openid、 Files.ReadWrite和 Mail.Read。

  7. 选中每个权限显示的复选框。 请注意，在选择每个权限时，这些权限不会在列表中保持可见。 选择加载项所需的权限后，选择“ 添加权限”。

    “请求 API 权限”窗格，其中选择了一些权限。

添加 webApplicationInfo 属性

若要在部署工作流中获取管理员同意，请将 webApplicationInfo 属性添加到统一清单。 将 id 属性设置为应用注册 ID。 将 resource 属性设置为域的值。 以下示例显示了 webApplicationInfo contoso.com 的应用注册的 属性。

    "webApplicationInfo": {
        "id": "a92ace55-9daf-47bc-84e9-065e9a6e70e3",
        "resource": "https://contoso.com"
    },

部署更新的清单

如果通过 Microsoft AppSource 部署了加载项，则需要提交更新的统一清单以供审批。 有关详细信息，请参阅 Microsoft AppSource 提交常见问题解答。

如果通过向管理员提供清单进行集中部署来部署加载项，则需要为管理员提供包含更新清单的更新 应用包 。

相关内容