使用本机身份验证在示例 iOS 移动应用中登录用户和调用 API - Microsoft Entra External ID

项目
06/17/2024

此示例演示如何配置 iOS 示例应用程序来调用 ASP.NET Core Web API。

先决条件

使用本机身份验证在示例 iOS (Swift) 移动应用中登录用户。

注册 Web API 应用程序

至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
如果你有权访问多个租户，请使用顶部菜单中的“设置”图标，通过“目录 + 订阅”菜单切换到你的外部租户。
浏览到“标识”>“应用程序”>“应用注册”。
选择“+ 新建注册”。
在出现的“注册应用程序”页面中，输入应用程序的注册信息：
1. 在“名称”部分中，输入将向应用用户显示的有意义的应用程序名称，例如“ciam-ToDoList-api”。
2. 在“支持的帐户类型”下，选择“仅此组织目录中的帐户” 。
选择“注册”以创建应用程序。
注册完成后，将显示应用程序的“概述”窗格。记录要在应用程序源代码中使用的目录（租户）ID 和应用程序（客户端）ID。

配置 API 范围

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

从“应用注册”页中，选择创建的 API 应用程序 (ciam-ToDoList-api) 以打开其“概述”页。
在“管理”下，选择“公开 API” 。
在页面顶部的“应用程序 ID URI”旁边，选择“添加”链接以生成对此应用来说独一无二的 URI。
接受建议的应用程序 ID URI，例如 api://{clientId}，然后选择“保存”。 Web 应用程序在请求 Web API 的访问令牌时，会将此 URI 添加为你为 API 定义的每个范围的前缀。
在“此 API 定义的范围”下选择“添加范围”。

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

属性	价值
作用域名	ToDoList.Read
谁可以许可	仅管理员
管理员许可显示名称	使用“ToDoListApi”读取用户待办事项列表
管理员同意说明	允许应用使用“TodoListApi”读取用户的待办事项列表。
状态	已启用

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

属性	价值
作用域名	ToDoList.ReadWrite
谁可以许可	仅管理员
管理员许可显示名称	使用“ToDoListApi”读写用户 ToDo 列表
管理员同意说明	允许应用使用“ToDoListApi”读写用户的 ToDo 列表
状态	已启用

在“管理”下，选择“清单”以打开 API 清单编辑器。
将 accessTokenAcceptedVersion 属性设置为 2。
选择“保存”。

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

配置应用角色

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

从“应用注册”页中，选择创建的应用程序（例如 ciam-ToDoList-api）以打开其“概述”页。
在“管理”下，选择“应用角色”。
选择“创建应用角色”，输入以下值，然后选择“应用”以保存更改：

属性值

显示名称 ToDoList.Read.All

允许的成员类型 应用程序

值 ToDoList.Read.All

说明 允许应用使用“TodoListApi”读写每个用户的待办事项列表
再次选择“创建应用角色”，为第二个应用角色输入以下值，然后选择“应用”以保存更改：

属性值

显示名称 ToDoList.ReadWrite.All

允许的成员类型 应用程序

值 ToDoList.ReadWrite.All

说明允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表

属性	值
显示名称	ToDoList.Read.All
允许的成员类型	应用程序
值	ToDoList.Read.All
说明	允许应用使用“TodoListApi”读写每个用户的待办事项列表

属性	值
显示名称	ToDoList.ReadWrite.All
允许的成员类型	应用程序
值	ToDoList.ReadWrite.All
说明	允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表

配置可选声明

可以包含 idtyp 可选声明，以帮助 Web API 确定令牌是应用令牌还是应用 + 用户令牌。尽管可以将 scp 和 roles 声明的组合用于同一目的，但使用 idtyp 声明仍是区分应用令牌和应用 + 用户令牌的最简单方法。例如，当令牌为仅限应用的令牌时，此声明的值为 app。

向 iOS 示例应用授予 API 权限

注册客户端应用和 Web API，并通过创建范围公开 API 后，可按照以下步骤来配置客户端对 API 的权限：

从“应用注册”页中，选择创建的应用程序（例如 ciam-client-app）以打开其“概述”页。
在“管理”下选择“API 权限” 。
在“已配置权限”下，选择“添加权限”。
选择“我的组织使用的 API”选项卡。
在 API 列表中，选择 API（例如 ciam-ToDoList-api）。
选择“委托的权限”选项。
从权限列表中，选择“ToDoList.Read”、“ToDoList.ReadWrite”（必要时使用搜索框）。
选择“添加权限”按钮。
此时，你已正确分配了权限。但是，由于租户是客户的租户，因此使用者用户本身不能同意这些权限。要解决此问题，作为管理员的你必须代表租户中的所有用户同意这些权限：
1. 选择“为 <租户名称> 授予管理员同意”，然后选择“是”。
2. 选择“刷新”，然后验证两个权限的“状态”下是否均显示“已为 <租户名称> 授予”。
从“配置的权限”列表中，选择“ToDoList.Read”和“ToDoList.ReadWrite”权限（一次选择一个），然后复制权限的完整 URI 供以后使用。完整权限 URI 看起来类似于 api://{clientId}/{ToDoList.Read} 或 api://{clientId}/{ToDoList.ReadWrite}。

克隆或下载示例 Web API

若要获取示例应用程序，可以从 GitHub 克隆它或将其下载为 .zip 文件。

若要克隆示例，请打开命令提示符并导航到要创建项目的位置，然后输入以下命令：
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
```
下载 .zip 文件。将其提取到名称长度小于 260 个字符的文件路径。

配置并运行示例 Web API

在代码编辑器中打开 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json 文件。
查找占位符：
- 查找 Enter_the_Application_Id_Here 并将其替换为之前复制的 Web API 的应用程序（客户端）ID。
- 查找 Enter_the_Tenant_Id_Here 并将其替换为之前复制的目录（租户）ID。
- 查找 Enter_the_Tenant_Subdomain_Here 并将其替换为目录（租户）子域。例如，如果租户主域为 contoso.onmicrosoft.com，请使用 contoso。如果没有租户名称，请了解如何读取租户详细信息。

需要为 iOS 示例应用托管 Web API 才能调用它。按照快速入门：部署 ASP.NET Web 应用来部署 Web API。

配置示例 iOS 移动应用来调用 Web API

在 Xcode 中，打开 /NativeAuthSampleApp/ProtectedAPIViewController.swift 文件。

查找 Enter_the_Protected_API_Full_URL_Here 并将此值替换为 Web API URL。

let protectedAPIUrl = "Enter_the_Protected_API_Full_URL_Here" // Developers should set the respective URL of their web API here

查找 Enter_the_Protected_API_Scopes_Here 并设置向 iOS 示例应用授予 API 权限中记录的范围。

let protectedAPIScopes = ["Enter_the_Protected_API_Scopes_Here"] // Developers should set the respective scopes of their web API here.For example, let protectedAPIScopes = ["api://{clientId}/{ToDoList.Read}","api://{clientId}/{ToDoList.ReadWrite}"]

运行 iOS 示例应用并调用 Web API

若要构建并运行应用，请执行以下步骤：

若要生成和运行代码，请从 Xcode 的“产品”菜单中选择“运行”。成功生成后，Xcode 将在模拟器中启动示例应用。
选择“API”选项卡以测试 API 调用。成功调用 Web API 将返回 HTTP 200，而 HTTP 403 表示未经授权的访问。

后续步骤

教程：准备 iOS 应用来进行本机身份验证。

通过