教程：生成使用 Microsoft 标识平台的多租户守护程序

  • 项目

在本教程中，你将下载并运行 ASP.NET 守护程序 Web 应用，该应用演示了如何使用 OAuth 2.0 客户端凭据授权获取用于调用 Microsoft Graph API 的访问令牌。

在本教程中：

  • 将守护程序应用与 Microsoft 标识平台集成
  • 由管理员直接向应用授予应用程序权限
  • 获取用于调用 Microsoft Graph API 的访问令牌
  • 调用 Microsoft Graph API。

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

先决条件

  • Visual Studio 2017 或 2019。
  • 一个 Microsoft Entra 租户。 有关详细信息，请参阅如何获取 Microsoft Entra 租户。
  • 租户中的一个或多个用户帐户。 本示例不适用于 Microsoft 帐户。 如果已使用 Microsoft 帐户登录并且从未在目录中创建过用户帐户，请立即执行此操作。

方案

该应用是作为 ASP.NET MVC 应用程序生成的。 它使用 OWIN OpenID Connect 中间件将用户登录。

本示例中的“守护程序”组件是 API 控制器 SyncController.cs。 该控制器被调用时，会从 Microsoft Graph 提取客户的 Microsoft Entra 租户中的用户列表。 SyncController.cs 由 Web 应用程序中的 AJAX 调用触发。 它使用适用于 .NET 的 Microsoft 身份验证库 (MSAL) 获取 Microsoft Graph 的访问令牌。

由于该应用是面向 Microsoft 企业客户的多租户应用，因此它必须为客户提供一种“注册”应用程序或将应用程序“连接”到其公司数据的方法。 在连接流期间，全局管理员首先将应用程序权限直接授予应用，使该应用能够以非交互方式访问公司数据，而无需用户登录。 本示例中的大部分逻辑介绍了如何使用标识平台管理员许可终结点来实现此连接流。

Diagram shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Microsoft Entra ID, AccountController getting admin consent to connect to Microsoft Entra ID, and SyncController reading user to connect to Microsoft Graph.

有关此示例中使用的概念的详细信息，请阅读标识平台的客户端凭据协议文档。

克隆或下载此存储库

在 shell 或命令行中输入以下命令：

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

或下载 zip 文件格式的示例。

注册应用程序

本示例包含一个项目。 若要将应用程序注册到 Microsoft Entra 租户，可执行以下操作：

  • 按照选择租户中的步骤进行操作，并将示例配置为使用租户。
  • 使用可执行以下操作的 PowerShell 脚本：
    • 自动创建 Microsoft Entra 应用程序和相关对象（密码、权限、依赖项）。
    • 修改 Visual Studio 项目的配置文件。

若要使用自动化：

  1. 请在 Windows 上运行 PowerShell，并转到克隆的目录的根目录。

  2. 运行以下命令：

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. 运行脚本以创建 Microsoft Entra 应用程序，并相应地配置示例应用程序的代码：

    .\AppCreationScripts\Configure.ps1

    应用创建脚本中介绍了运行脚本的其他方式。

  4. 打开 Visual Studio 解决方案，选择“启动”以运行代码。

如果不想要使用自动化，请使用以下部分中的步骤。

选择租户

提示

本文中的步骤可能因开始使用的门户而略有不同。

  1. 至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。

  2. 如果你有权访问多个租户，请使用顶部菜单中的“设置”图标 ，通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。

  3. 浏览到“标识”>“应用程序”>“应用注册”。

  4. 选择“新注册”。

  5. 输入应用程序的名称（例如 dotnet-web-daemon-v2）。 应用的用户可能会看到此名称，你稍后可对其进行更改。

  6. 在“支持的帐户类型”部分，选择“任何组织目录中的帐户”。

  7. 在“重定向 URI (可选)”部分的组合框中选择“Web”，然后输入以下重定向 URI：https://localhost:44316/ 和 https://localhost:44316/Account/GrantPermissions 。

    如果有两个以上的重定向 URI，则需要在成功创建应用后，从“身份验证”选项卡中添加这些 URI。

  8. 选择“注册”以创建应用程序。

  9. 在应用的“概述”页上，找到“应用程序(客户端) ID”值，并记下该值以供后续使用 。 稍后需要使用它为此项目配置 Visual Studio 配置文件。

  10. 在“管理”下，选择“身份验证”。

  11. 将“前向通道注销 URL”设置为 https://localhost:44316/Account/EndSession。

  12. 在“隐式授权和混合流”部分，选择“访问令牌”和“ID 令牌” 。 本示例需要启用隐式授权流，使用户能够登录并调用 API。

  13. 选择“保存”。

  14. 在“管理”下，选择“证书和机密”。

  15. 在“客户端密码”部分中，选择“新建客户端密码” 。

  16. 输入密钥说明（例如“应用机密”）。

  17. 选择密钥持续时间（“1 年”、“2 年”或“永不过期”） 。

  18. 选择 添加 。 将密钥值记录在安全的位置。 稍后将需要此密钥来配置 Visual Studio 中的项目。

  19. 在“管理”下，选择“API 权限”>“添加权限” 。

  20. 在“常用 Microsoft API”部分，选择“Microsoft Graph”。

  21. 在“应用程序权限”部分，确保已选择适当的权限： User.Read.All。

  22. 选择“添加权限”。

将示例配置为使用租户

在以下步骤中，ClientID 等同于“应用程序 ID”或 AppId。

在 Visual Studio 中打开解决方案以配置项目。

配置客户端项目

如果使用了安装脚本，将应用以下更改。

  1. 打开 UserSync\Web.Config 文件。
  2. 找到应用密钥 ida:ClientId。 将现有值替换为之前记录的“dotnet-web-daemon-v2”应用程序的应用程序 ID。
  3. 找到应用密钥 ida:ClientSecret。 将现有值替换为创建“dotnet-web-daemon-v2”应用期间保存的密钥。

运行示例

清理解决方案，重新生成解决方案，运行 UserSync 应用程序，然后以管理员身份登录到 Microsoft Entra 租户中。 如果没有用于测试的 Microsoft Entra 租户，可按照这些说明获取租户。

登录时，应用首先会请求提供所需的权限，以便能够将你登录并读取你的用户配置文件。 应用通过这种许可来确保你是企业用户。

User consent

然后，应用会尝试通过 Microsoft Graph 从 Microsoft Entra 租户同步用户列表。 如果无法同步，它会请求你（租户管理员）将租户连接到应用。

然后，应用将请求读取租户中用户列表的权限。

Admin consent

授予权限后，你将从应用注销。 这种注销可确保从令牌缓存中删除 Microsoft Graph 的所有现有访问令牌。 再次登录时，获取的新令牌将拥有调用 Microsoft Graph 所需的权限。

在你授予权限后，应用随时可以查询用户。 可以通过选择“同步用户”按钮并刷新用户列表来确认这一点。 尝试添加或删除用户，并重新同步列表。 （但请注意，应用只会同步第一页中的用户。）

关于代码

此示例的相关代码在以下文件中：

  • App_Start\Startup.Auth.cs、Controllers\AccountController.cs：初始登录 具体而言，控制器上的操作具有 Authorize 属性，该属性将强制用户登录。 应用程序使用授权代码流，以便于用户登录。
  • Controllers\SyncController.cs：将用户列表同步到本地内存中存储。
  • Controllers\UserController.cs：显示本地内存中存储中的用户列表。
  • Controllers\AccountController.cs：使用管理员许可终结点从租户管理员获取权限。

重新创建示例应用

  1. 在 Visual Studio 中，创建新的 Visual C#ASP.NET Web 应用程序(.NET Framework) 项目。
  2. 在下一屏幕中选择“MVC”项目模板。 另外，请为 Web API 添加文件夹和核心引用，因为稍后要添加 Web API 控制器。 将项目的所选身份验证模式保留为默认设置：“无身份验证”。
  3. 在“解决方案资源管理器”窗口中选择该项目，然后按 F4 键。
  4. 在项目属性中，将“已启用 SSL”设置为“True”。 记下“SSL URL”中的信息。 在 Azure 门户中配置此应用程序的注册时需要用到这些信息。
  5. 添加以下 ASP.NET OWIN 中间件 NuGet 包：
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. 在 App_Start 文件夹中：
    1. 创建名为 Startup.Auth.cs 的类。
    2. 从命名空间名称中删除 .App_Start。
    3. 将 Startup 类的代码替换为示例应用的同一文件中的代码。 请务必使用整个类定义。 定义将从 public class Startup 更改为 public partial class Startup。
  7. 在 Startup.Auth.cs中，通过添加 Visual Studio IntelliSense 建议的 using 语句来解决缺少引用的问题。
  8. 右键单击该项目，然后依次选择“添加”、“类”。
  9. 在搜索框中输入 OWIN。 “OWIN Startup 类”将作为一个选项显示。 选择该选项，将类命名为 Startup.cs。
  10. 在 Startup.cs 中，将 Startup 类的代码替换为示例应用的同一文件中的代码。 同样请注意，定义将从 public class Startup 更改为 public partial class Startup。
  11. 在 Models 文件夹中，添加名为 MsGraphUser.cs 的新类。 将实现替换为示例中同名文件的内容。
  12. 添加名为 AccountController 的“MVC 5 控制器 - 空”新实例。 将实现替换为示例中同名文件的内容。
  13. 添加名为 UserController 的“MVC 5 控制器 - 空”新实例。 将实现替换为示例中同名文件的内容。
  14. 添加名为 SyncController 的“Web API 2 控制器 - 空”新实例。 将实现替换为示例中同名文件的内容。
  15. 对于用户界面，请在 Views\Account 文件夹中，添加名为 GrantPermissions、Index 和 UserMismatch 的三个“空(无模型)视图”实例。 在 Views\User 文件夹中添加一个名为 Index 的实例。 将实现替换为示例中同名文件的内容。
  16. 更新 Shared_Layout.cshtml 和 Home\Index.cshtml 以正确地将各个视图链接到一起。

将示例部署到 Azure

此项目包含 Web 应用和 Web API 项目。 若要将这些项目部署到 Azure 网站，请对每个项目执行以下步骤：

  1. 创建一个 Azure 网站。
  2. 将 Web 应用和 Web API 发布到该网站。
  3. 更新客户端以调用该网站而不是调用 IIS Express。

创建 dotnet-web-daemon-v2 并将其发布到 Azure 网站

  1. 登录 Azure 门户。
  2. 在左上角，选择“创建资源”。
  3. 选择“Web”>“Web 应用”，然后为网站命名。 例如，将它命名为 dotnet-web-daemon-v2-contoso.azurewebsites.net。
  4. 选择“订阅”、“资源组”和“应用服务计划和位置”的信息。 为“OS”选择“Windows”，为“发布”选择“代码”。
  5. 选择“创建”，等待创建完应用服务。
  6. 出现“部署成功”通知后，选择“转到资源”以转到新建的应用服务。
  7. 创建网站后，在“仪表板”中找到它，并将其选中以打开应用服务的“概述”屏幕。
  8. 在应用服务的“概述”选项卡中，选择“获取发布配置文件”链接下载该配置文件并保存。 可以使用其他部署机制，例如，从源代码管理进行部署。
  9. 切换到 Visual Studio，然后：
    1. 转到 dotnet-web-daemon-v2 项目。
    2. 在解决方案资源管理器中右键单击该项目，然后选择“发布”。
    3. 在底部栏上选择“导入配置文件”，然后导入先前下载的发布配置文件。
  10. 选择“配置” 。
  11. 在“连接”选项卡上更新目标 URL，使其使用“https”。例如使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net。 选择“下一步”。
  12. 在“设置”选项卡上，确保已清除“启用组织身份验证”。
  13. 选择“保存”。 在主屏幕上选择“发布”。

Visual Studio 将发布项目，同时自动打开浏览器并加载该项目的 URL。 如果看到该项目的默认网页，则表示发布成功。

更新 dotnet-web-daemon-v2 的 Microsoft Entra 租户应用程序注册

  1. 返回到 Microsoft Entra 管理中心，然后在“应用注册”中选择“dotnet-web-daemon-v2”应用程序。
  2. 在应用程序的“身份验证”页上，使用服务地址更新“前向通道注销 URL”字段 。 例如，使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession。
  3. 在“品牌”菜单中，将“主页 URL”更新为服务地址。 例如，使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net。
  4. 保存配置。
  5. 在“身份验证”>“重定向 URI”菜单的值列表中添加相同的 URL。 如果有多个重定向 URL，请确保每个重定向 URL 都有一个使用应用服务的 URI 的新条目。

清理资源

如果不再需要，请删除注册应用程序 步骤中创建的应用对象。 若要删除应用程序，请按照删除你或你的组织编写的应用程序中的说明进行操作。

获取帮助

使用 Microsoft Q&A 获取社区的支持。 先在 Microsoft Q&A 上提问并浏览现有问题，查看是否已有人提出过相同的问题。 请务必将提问或评论用 azure-ad-adal-deprecation、azure-ad-msal 和 dotnet-standard 标记。

如果发现示例中有错误，请在 GitHub 问题上提出问题。

如果发现 MSAL.NET 中有错误，请在 MSAL.NET GitHub 问题上提出问题。

若要提供建议，请转到 User Voice 页。

后续步骤

详细了解如何生成使用 Microsoft 标识平台访问受保护的 Web API 的守护程序应用：

方案：用于调用 Web API 的守护程序应用程序