使用本机身份验证在示例 iOS 移动应用中登录用户并调用 API

适用于： 员工租户 外部租户（了解详细信息）

本快速入门介绍如何配置 iOS 示例应用程序以调用 ASP.NET Core Web API。

先决条件

• 通过 iOS 本地身份验证在 Swift 编写的移动应用示例中为用户登录。
• 在 Microsoft Entra 管理中心为您的 web API 注册一个新应用，并配置为支持 任何组织目录中的帐户和个人 Microsoft 帐户。 有关更多详细信息 ，请参阅注册应用程序 。 在应用程序 概述 页中记录以下值供以后使用：
  • 应用程序（客户端）ID
  • 目录（租户）ID

注册 Web API 应用程序

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

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

3. 浏览到 Entra ID>应用注册。

4. 选择“+ 新建注册”。

5. 在出现的“注册应用程序”页面中，输入应用程序的注册信息：

   1. 在“名称”部分中，输入将向应用用户显示的有意义的应用程序名称，例如“ciam-ToDoList-api”。

   2. 在“支持的帐户类型”下，选择“仅此组织目录中的帐户”。

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

7. 注册完成后，将显示应用程序的“概述”窗格。 记录在应用程序源代码中使用的 目录（租户）ID 和 应用程序（客户端）ID 。

配置 API 范围

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”读取用户 ToDo 列表
   管理员同意说明	允许应用使用“TodoListApi”读取用户的 ToDo 列表。
   国家	已启用

7. 再次选择 “添加范围 ”，并输入以下值，用于定义 API 的读取和写入访问范围。 选择 “添加范围 ”以保存更改：

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

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

配置应用角色

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

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

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

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

   财产	价值
   显示名称	ToDoList.Read.All
   允许的成员类型	应用
   价值	ToDoList.Read.All
   说明	允许应用使用“TodoListApi”读取每个用户的 ToDo 列表
   要启用此应用角色吗？	保持选中状态

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

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

配置可选声明

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

向 iOS 示例应用授予 API 权限

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

1. 在 “应用注册 ”页中，选择你创建的应用程序（如 ciam-client-app），以打开其 “概述 ”页。

2. 在“ 管理”下，选择 API 权限。

3. 在“已配置权限”下，选择“添加权限”。

4. 选择“我的组织使用的 API”选项卡。

5. 在 API 列表中，选择 API（例如 ciam-ToDoList-api）。

6. 选择“委托的权限”选项。

7. 从权限列表中，选择“ToDoList.Read”、“ToDoList.ReadWrite”（必要时使用搜索框）。

8. 选择“添加权限”按钮。

9. 此时，你已正确分配了权限。 但是，由于租户是客户的租户，因此消费者用户本身不能同意这些权限。 若要解决此问题，管理员必须代表租户中的所有用户同意这些权限：

   1. 选择“为<租户名称>授予管理员同意”，然后选择“是”。

   2. 选择“刷新”，然后验证两个权限的“状态”下是否均显示“已为 租户名称< 授予”>。

10. 从“配置的权限”列表中，选择“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

1. 在代码编辑器中打开 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json 文件。

2. 查找占位符：

   • 查找 Enter_the_Application_Id_Here 并将其替换为之前复制的 Web API 的“应用程序(客户端) ID”。
   • 查找 Enter_the_Tenant_Id_Here 并将其替换为之前复制的“目录(租户) ID”。
   • Enter_the_Tenant_Subdomain_Here 并将其替换为 Directory （tenant） 子域。 例如，如果租户主域名是 contoso.onmicrosoft.com，请使用 contoso。 如果没有租户名称，请了解如何 阅读租户详细信息。

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

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

此示例允许配置多个 Web API URL 终结点和范围集。 在这种情况下，仅配置一个 Web API URL 终结点及其关联的范围。

1. 在 Xcode 中，打开 /NativeAuthSampleApp/ProtectedAPIViewController.swift 文件。 如果您正在使用 macOS，下面是 ProtectedAPIViewController.swift 代码文件的一个示例。

2. 查找 protectedAPIUrl1 并输入 Web API URL 作为其值。

   let protectedAPIUrl1: String? = nil // Developers should set the respective URL of their web API here. For example let protectedAPIUrl1: String? = "https://api.example.com/v1/resource"
   

3. 查找 protectedAPIScopes1 并设置在 授予 API 权限中记录到 iOS 示例应用的范围。

   let protectedAPIScopes1: [String] = [] // 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

若要生成并运行应用，请执行以下步骤：

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

后续步骤

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