快速入门：调用受Microsoft标识平台保护的 Web API

• Visual Studio 2022。 免费下载 Visual Studio。

• Visual Studio Code

1. 在管理下，选择公开 API>添加范围。 通过选择“保存并继续”来接受建议的应用程序 ID URI (api://{clientId})，然后输入以下信息：

   1. 对于范围名称，请输入access_as_user。
   2. 对于“谁能同意?”，请确保选择了“管理员和用户”选项。
   3. 在“管理员同意显示名称”框中，输入 Access TodoListService as a user。
   4. 在“管理员同意说明”框中，输入 Accesses the TodoListService web API as a user。
   5. 在“用户同意显示名称”框中，输入 Access TodoListService as a user。
   6. 在“用户同意说明”框中，输入 Accesses the TodoListService web API as a user。
   7. 对于“状态”，保留“启用”。

2. 选择添加作用域。

添加委托的权限（范围）

API 需要至少发布一个范围（也称为委托的权限），客户端应用才能成功获取用户的访问令牌。 若要发布范围，请执行以下步骤：

1. 从“应用注册”页中，选择创建的 API 应用程序 (ciam-ToDoList-api) 以打开其“概述”页。

2. 在“管理”下，选择“公开 API” 。

3. 在页面顶部的“应用程序 ID URI”旁边，选择“添加”链接以生成对此应用来说独一无二的 URI。

4. 接受建议的应用程序 ID URI，例如 api://{clientId}，然后选择“保存”。 当您的 Web 应用在请求 Web API 的访问令牌时，会将该 URI 添加为 API 每个定义范围的前缀。

5. 在“此 API 定义的范围”下选择“添加范围”。

6. 输入以下值，用于定义对 API 的读取访问权限，然后选择添加范围以保存更改：

   房产	价值
   范围名称	ToDoList.Read
   谁可以许可	仅管理员
   管理员同意显示名称	使用“ToDoListApi”读取用户待办事项列表
   管理员同意说明	允许应用使用“TodoListApi”读取用户的待办事项列表。
   国家	已启用

7. 再次选择添加范围，然后输入定义对 API 的读取和写入访问权限范围的以下值。 选择“添加作用域”，保存所做更改：

   房产	价值
   范围名称	ToDoList.ReadWrite
   谁可以许可	仅管理员
   管理员同意显示名称	使用“ToDoListApi”读写用户 ToDo 列表
   管理员同意说明	允许应用使用“ToDoListApi”读写用户的 ToDo 列表
   国家	已启用

详细了解 Web API 的发布权限时的最小特权原则。

添加应用程序权限（应用角色）

API 需要为应用程序发布至少一个应用角色（也称为 应用程序权限），客户端应用才能自行获取访问令牌。 应用程序权限是 API 想要使客户端应用程序能够成功地以自己的身份进行身份验证（无需让用户登录）时应发布的权限类型。 若要发布应用程序权限，请执行下列步骤：

1. 从“应用注册”页中，选择创建的应用程序（例如 ciam-ToDoList-api）以打开其“概述”页。

2. 在“管理”下，选择“应用角色”。

3. 选择“创建应用角色”，输入以下值，然后选择“应用”以保存更改：

   房产	价值
   显示名称	ToDoList.Read.All
   允许的成员类型	应用程序
   价值	ToDoList.Read.All
   DESCRIPTION	允许应用使用“TodoListApi”读写每个用户的待办事项列表
   要启用此应用角色吗？	保持选中状态

4. 再次选择“创建应用角色”，为第二个应用角色输入以下值，然后选择“应用”以保存更改：

   房产	价值
   显示名称	ToDoList.ReadWrite.All
   允许的成员类型	应用程序
   价值	ToDoList.ReadWrite.All
   DESCRIPTION	允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表
   要启用此应用角色吗？	保持选中状态

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• 以 ZIP 文件下载。

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• 下载 .zip 文件。 将其解压缩到名称长度少于 260 个字符的文件路径。

1. 在 Visual Studio 中打开解决方案，然后在 TodoListService 项目的根目录下打开 appsettings.json 文件。

2. 将 Enter_the_Application_Id_here 的值替换为在“应用注册”门户中的 和 ClientID 参数中注册的应用程序中的客户端 ID（应用程序 ID）值Audience。

将新范围添加到 app.config 文件

若要将新范围添加到 TodoListClient app.config 文件，请执行以下步骤：

1. 在 TodoListClient 项目根文件夹中，打开 app.config 文件。

2. 将你为 TodoListService 项目注册的应用程序的 ID 粘贴到 TodoListServiceScope 参数中，替换 {Enter the Application ID of your TodoListService from the app registration portal} 字符串。

注册 Web 应用 （TodoListClient）

在 Microsoft Entra 管理中心 的应用注册 中注册 TodoListClient 应用，然后在 TodoListClient 项目中配置代码。 如果客户端和服务器被视为同一应用程序，则可以重复使用在步骤 2 中注册的应用程序。 如果希望用户使用 Microsoft 个人帐户登录，则可使用相同的应用程序。

注册应用

若要注册 TodoListClient 应用，请执行以下步骤：

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

2. 浏览到 Entra ID>应用注册 并选择“ 新建注册”。

3. 选择“新注册”。

4. “注册应用程序”页出现后，请输入应用程序的注册信息：

   1. 在 名称 部分中，输入一个有意义的应用程序名称，该名称将显示给应用的用户（例如，NativeClient-DotNet-TodoListClient）。
   2. 在“支持的帐户类型”下，选择“任何组织目录中的帐户” 。
   3. 选择“注册”以创建应用程序。

   注释

   在 TodoListClient 项目 app.config 文件中，ida:Tenant 的默认值设置为 common。 可能的值为：

   • common：可以使用工作或学校帐户或 Microsoft 个人帐户登录（因为你在上一步中选择了“任何组织目录中的帐户”）。
   • organizations：可使用工作或学校帐户登录。
   • consumers：只能使用 Microsoft 个人帐户登录。

5. 在应用 概述 页上，选择 身份验证，然后完成以下步骤以添加平台：

   1. 在“平台配置”下，选择“添加平台”按钮 。
   2. 对于 移动和桌面应用程序，请选择 移动和桌面应用程序。
   3. 对于“重定向 URI”，请选择 复选框。https://login.microsoftonline.com/common/oauth2/nativeclient
   4. 选择配置。

6. 选择“API 权限”，然后完成以下步骤以添加权限：

   1. 选择“添加权限”按钮。
   2. 选择“我的 API”选项卡。
   3. 在 API 列表中，选择 AppModelv2-NativeClient-DotNet-TodoListService API 或选择您为 Web API 输入的名称。
   4. 如果"access_as_user"权限框未选中，请选中它。 如有必要，请使用“搜索”框。
   5. 选择“添加权限”按钮。

配置您的项目

通过将应用程序 ID 添加到 app.config 文件来配置 TodoListClient 项目。

1. 在“应用注册门户”的“概述”页中，复制“应用程序(客户端) ID”的值 。

2. 从 TodoListClient 项目根文件夹打开 app.config 文件，然后将应用程序 ID 值粘贴到 ida:ClientId 参数中。

1. 在 IDE 中，打开包含示例的项目文件夹 ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI。

2. 打开 appsettings.json 文件，其中包含以下代码片段：

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   查找以下值：

   • ClientId - 应用程序的标识符，也称为客户端。 将引号中的 value 文本替换为先前从注册应用程序的“概述”页中记录的应用程序（客户端）ID。
   • TenantId - 应用程序注册所在租户的标识符。 将引号中的 value 文本替换为注册应用程序“概述页”中先前记录的 目录（租户）ID 值。
   • Instance - 它指定Microsoft身份验证库（MSAL）可从中请求令牌的目录。 根据您的情况，将 Enter_the_Authority_URL_Here 替换为以下任一值：
     • 对于员工租户，请使用 https://login.microsoftonline.com/ 作为实例。
     • 对于外部租户，以https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/的形式添加权威 URL

启动这两个项目。 对于 Visual Studio 用户;

1. 右键单击 Visual Studio 解决方案，然后选择“属性”

2. 在 “通用属性”中，选择“ 启动项目 ”，然后选择 “多个启动项目”。

3. 对于这两个项目，请选择“启动”作为操作

4. 请使用向上箭头将 TodoListService 服务移动到列表中的第一个位置，以确保先启动该服务。

登录以运行 TodoListClient 项目。

1. 按 F5 启动项目。 服务页面和桌面应用程序同时打开。

2. 在 TodoListClient 中，选择右上角的“登录”，然后使用注册应用程序时所用的同一凭据登录，或以同一目录中的用户身份登录。

   如果首次登录，系统可能会提示你同意 TodoListService Web API。

   为了帮助你访问 TodoListService Web API 并操作 待办事项 列表，登录还请求访问 access_as_user 作用域的访问令牌。

为客户端应用程序预先授权

可以允许其他目录中的用户访问 Web API，方法是预先授权客户端应用程序访问 Web API。 为此，请将来自客户端应用的应用程序 ID 添加到你的 Web API 的预授权应用列表中。 通过添加预授权客户端，你可以允许用户访问 Web API，而无需提供同意。

1. 在“应用注册”门户中，打开 TodoListService 应用的属性。
2. 在“公开 API”部分的“授权客户端应用程序”下，选择“添加客户端应用程序。
3. 在“客户端 ID”框中，粘贴 TodoListClient 应用的应用程序 ID。
4. 在 授权范围 部分中，选择 api://<Application ID>/access_as_user Web API 的范围。
5. 选择添加应用程序。

开始运行项目

1. 按 F5 运行项目。 您的 TodoListClient 应用打开了。
2. 选择右上角的“登录”，然后使用 Microsoft 个人帐户（例如 live.com 或 hotmail.com 帐户）或工作或学校帐户登录 。

可选：限制特定用户的登录访问权限

默认情况下，任何个人帐户（例如 outlook.com 或 live.com 帐户）或与 Microsoft Entra ID 集成的组织的工作或学校帐户都可以请求令牌并访问 Web API。

若要通过更改 TenantId 文件中 属性来指定谁可以登录到应用程序。

1. 从 Web API 项目目录的根目录运行以下命令以启动应用：

   dotnet run
   

2. 如果一切正常，终端将显示如下所示的输出：

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   记录 https://localhost:{port} URL 中的端口号。

3. 若要验证终结点是否受保护，请更新下面的 cURL 命令中的基 URL 以匹配在上一步中收到的终结点，然后运行该命令：

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   预期响应为 401 未授权。