通过

适用于 MAM 的 Microsoft Tunnel iOS SDK 开发人员指南

  • 项目

注意

将Microsoft Intune计划 2 或Microsoft Intune Suite添加为附加许可证时，此功能可用。 有关详细信息，请参阅使用 Intune 套件加载项功能。

适用于 MAM 的 Microsoft Tunnel iOS SDK 开发人员指南是面向开发人员的资源。 它可帮助开发人员将 SDK 集成到 iOS/iPadOS 应用中并对其进行配置。 有关适用于 MAM 的 Microsoft Tunnel的概述，请转到适用于 iOS/iPadOS 的适用于 MAM 的 Microsoft Tunnel - Intune管理员指南。

本指南介绍了 Xcode 应用项目中集成过程的不同部分，包括安装框架、配置文件 info.plist 、生成设置、密钥共享和实现 SDK 的委托方法。

这些组件在开发 iOS/iPadOS 应用时至关重要。 开发人员必须了解如何导航和配置 SDK 组件。 如果你不熟悉 Xcode 和 iOS/iPadOS 应用开发，则本指南可以提供帮助。 它概述了在何处查找不同的 SDK 组件以及如何在应用项目中使用这些元素。

此功能适用于：

  • iOS/iPadOS

SDK 存储库中的内容

SDK 存储库包含以下框架。 在后面的步骤中，你将将这些框架添加到应用项目中：

  • crypto.xcframework
  • MCPCommon.xcframework
  • MCPCore.xcframework
  • MCPPluginUnencryptedFile.xcframework
  • MicrosoftTunnelApi.xcframework
  • MSTAPNextPluginSecurityOpenssl.xcframework
  • MSTAPNextPluginSwiftSupport.xcframework
  • MSTAPNextPluginVpnMicrosoftTunnel.xcframework
  • ssl.xcframework

先决条件

若要使用 适用于 MAM 的 Microsoft Tunnel iOS SDK，需要满足以下先决条件：

  • 安装了 Xcode 14.0 或更高版本的 macOS 计算机

  • 你的业务线 (LOB) iOS/iPadOS 应用必须面向 iOS/iPadOS 14.0 或更高版本。

  • 需要下载两个 GitHub SDK 并将其与 Xcode 中的 iOS 应用集成。 在继续使用 适用于 MAM 的 Microsoft Tunnel iOS SDK 之前，请确保以下项目生成成功：

    1. Intune应用 SDK for iOS (打开 GitHub 站点) ：至少安装 16.1.1 版本。

      在此站点上，还查看Microsoft许可条款Intune适用于 iOS 的应用 SDK 文件。

      对于记录，请保留许可条款的副本。 下载和使用 适用于 MAM 的 Microsoft Tunnel iOS SDK 即表示你同意许可条款。 如果你不接受许可条款，请不要使用该软件。

    2. Microsoft身份验证库 (MSAL) (打开 GitHub 站点) ：至少安装 1.2.3 版本。

  • 安装并设置 适用于 MAM 的 Microsoft Tunnel iOS SDK (打开 GitHub 站点) 。 本文重点介绍此 SDK。

    重要

    Intune定期发布适用于 MAM 的 Microsoft Tunnel iOS SDK 的更新。 定期检查适用于 MAM 的 Microsoft Tunnel iOS SDK 进行更新。 将这些更新添加到软件开发发布周期。 你希望确保应用支持Microsoft Tunnel 网关更新和功能增强。

适用于 MAM 的 Microsoft Tunnel iOS SDK 的工作原理

MAM iOS SDK 的 Tunnel 使 iOS/iPadOS 应用能够建立“应用内”VPN 连接。 VPN 连接仅存在于应用中。

总之，这些应用内 VPN 连接包括：

  • 离散的，而不是设备级 VPN 连接
  • 范围仅限于应用程序网络层

当应用进行网络调用时，SDK 会截获网络调用并建立 VPN 连接。 此应用内 VPN 连接不会显示在 iOS/iPadOS 设备上的“设置”应用中。

体系结构：MAM iOS SDK 的隧道

下图描述了托管应用的流，该流已成功与 Tunnel for MAM iOS SDK 集成：

Microsoft Intune 中 iOS/iPadOS 上用于 MAM 的Microsoft隧道网关体系结构的绘图。

  1. 首次启动应用后，将使用适用于 iOS 的 适用于 MAM 的 Microsoft Tunnel SDK 建立连接。

  2. 隧道从 Microsoft Entra ID 获取设备身份验证令牌。

    如果设备登录到另一个启用了 MAM 的应用（如 Outlook、Edge 或 Microsoft 365 移动应用），则设备可能已具有Microsoft Entra身份验证令牌。 如果已存在有效的身份验证令牌，则使用现有令牌。

  3. 发生 TCP 连接，这是令牌和隧道服务器之间的 TLS 握手。

  4. 如果在Microsoft隧道网关上启用了 UDP，则会使用 DTLS 建立数据通道连接。 如果禁用 UDP，则 TCP 会建立到隧道网关的数据通道。

    有关详细信息，请转到 Microsoft隧道概述 - 体系结构中的 TCP 和 UDP 说明。

  5. 当移动应用连接到本地公司资源时：

    1. 适用于 MAM 的 Microsoft Tunnel API 请求连接到公司资源。
    2. 将创建加密的 Web 请求并将其发送到公司资源。

Xcode 任务

本部分列出并介绍了必须完成的 Xcode 任务，包括：

  • 添加框架和库
  • 查看并更新以下功能：
    • info.plist文件
    • 生成设置
    • 密钥链共享
  • 使用示例更新 Xcode AppDelegate 项目并添加Microsoft Tunnel 委托文件

步骤 1 - 添加框架和库

以下框架包括与 Intune Microsoft Tunnel Gateway 通信所需的 API 和委托方法。 他们在应用中实现 Microsoft Tunnel VPN 功能。

若要为 MAM iOS SDK 启用 Tunnel，请使用以下步骤：

  1. 将 Tunnel for MAM iOS SDK 下载并解压缩到 macOS 计算机上的某个文件夹。 先决条件中也列出了此任务。

    将以下 9 个框架复制到 Xcode 应用项目框架文件夹：

    • crypto.xcframework
    • MCPCommon.xcframework
    • MCPCore.xcframework
    • MCPPluginUnencryptedFile.xcframework
    • MicrosoftTunnelApi.xcframework
    • MSTAPNextPluginSecurityOpenssl.xcframework
    • MSTAPNextPluginSwiftSupport.xcframework
    • MSTAPNextPluginVpnMicrosoftTunnel.xcframework
    • ssl.xcframework

  2. 在 Xcode 项目中，选择应用项目 >“添加文件”。 在以下示例中，文件将添加到名为“Flash Chat”的应用项目中：

    显示如何在 macOS 设备上的 Xcode 中将文件添加到应用项目的屏幕。

  3. 在 “项目>目标”中，选择“ 生成阶段>嵌入框架”。 +) 所有九个框架添加 (：

    显示 macOS 设备上的 Xcode 中嵌入框架的屏幕截图。

    以下示例显示了添加的所有 9 个框架：

    显示 macOS 设备上 Xcode 中嵌入的所有Microsoft Tunnel 框架的屏幕截图。

  4. 在 “项目>目标”中，选择“ 生成阶段>链接二进制文件与库”。 在列表中，只 MicrosoftTunnelApi.xcframework 应添加框架。 如果列出了其他框架，请使用减 () - 将其删除：

    显示如何在 macOS 设备上的 Xcode 中使用库链接二进制文件中的框架的屏幕截图。

步骤 2 - 更新 info.plist 文件

info.plist在 Xcode 应用项目的 中，确认以下设置：

  • 捆绑 ID：确保 iOS 移动应用的 Microsoft Entra 应用注册中列出的捆绑包 ID 与应用项目中的捆绑 ID 相同：

    若要检查捆绑包 ID，请执行以下操作：

    1. 转到“项目>目标”“>常规”。

    2. 选择“ 标识>捆绑标识符”：

      显示选择项目、目标、常规和标识以在 macOS 设备上的 Xcode 中添加捆绑包 ID 的屏幕截图。

  • URL 类型：在 “项目>目标”中，选择“ 信息”。

    在“URL 类型”中$(PRODUCT_BUNDLE_IDENTIFIER)，确认变量是否存在。 将 Intune App SDK for iOS 与应用项目集成 (所需的先决条件) 时，应已创建此变量。

    如果该变量不存在，则需要添加它：

    1. 使用适用于 iOS 的 Intune App SDK (必需的先决条件) ，创建 info.plistArray 属性并将其命名为“查询 URL 方案”。

      添加 Intune App SDK for iOS 开发人员指南 - 步骤 5 中列出的字符串项。 此步骤创建Intune MAM SDK URL 方案。

      以下示例显示了使用 “查询的 URL 方案”的 info.plist：

      显示选择 macOS 设备上的 Xcode 中的项目、目标、信息、查询的 URL 方案值的屏幕截图。

    2. $(PRODUCT_BUNDLE_IDENTIFIER)添加 变量。

      以下示例显示了 $(PRODUCT_BUNDLE_IDENTIFIER)URL 类型中的 变量：

      显示选择 macOS 设备上的 Xcode 中的项目、目标、信息、URL 类型的屏幕截图。

  • IntuneMAMSettings：确认以下 MSAL 设置配置了相应的Microsoft Entra应用注册值：

    1. 转到 “项目>目标>信息”。

    2. 选择“ IntuneMAMSettings”。 确认设置：

      • ADALAuthority：输入Microsoft Entra租户 ID，如 https://login.microsoftonline.com/USE_YOUR_ Directory (tenant) ID。
      • ADALClientId：输入应用程序客户端 ID。
      • ADALRedirectUri：输入 msauth.$(PRODUCT_BUNDLE_IDENTIFIER):/auth。

    将 Intune App SDK for iOS 与应用项目集成 (所需的先决条件) 时，应已配置这些设置。

    如果未配置这些设置，则需要对其进行配置。 若要创建 IntuneMAMSettings info.plist Dictionary 属性和关联的Microsoft身份验证库字符串，请按照配置 Intune 应用 SDK 指南中的 Intune App SDK for iOS (必需的先决条件) 开发人员指南进行操作。

    以下示例显示了配置的这些值：

    显示选择 macOS 设备上的 Xcode 中的项目、目标、信息、IntuneMAMSetting 的屏幕截图。

步骤 3 - 关闭 Bitcode

  1. 转到 “项目>目标”“>生成设置”。
  2. 选择“ 生成”选项>“启用 Bitcode”。
  3. 选择“ 否”。

显示选择项目、目标、生成设置、生成选项以及禁用 macOS 设备上的 Xcode 位码的屏幕截图。

步骤 4 - 添加密钥链共享

密钥链共享可能存在于应用项目中，也可能不存在。 如果不存在，请添加它：

  1. 转到 “项目>目标签名>& 功能”。
  2. 选择“ 密钥链共享”。
  3. 在“密钥链组”列表中，添加 (+) com.microsoft.workplacejoin。

显示选择项目、目标、签名 & 功能、密钥链共享以及添加 macOS 设备上的 Xcode 中的密钥链组的屏幕截图。

步骤 5 - 将 SDK 与应用集成

✔️ 使用 TunnelMAMTestApp2.xcproject 示例应用。

根据 LOB 应用及其实现/预期目的，使用 MicrosoftTunnelApi 可能会有所不同。 将 SDK 与应用集成时，需要了解一些核心功能：

  • 与 适用于 MAM 的 Microsoft Tunnel iOS SDK 的所有交互都通过单一MicrosoftTunnelAPI实例对象进行处理。
  • 对象 MicrosoftTunnelAPI 使用实现 MicrosoftTunnelDelegate 接口的委托与应用交互。 

若要了解如何编写 Microsoft Tunnel 委托以及如何初始化 MicrosoftTunnelAPI，请使用 适用于 MAM 的 Microsoft Tunnel iOS SDK 示例应用 (打开 GitHub 站点) 。

在示例应用中，Xcode 项目 AppDelegate 显示：

  • 如何处理 MSAL URL 回调
  • 如何启动 Tunnel 所需的注册和初始化过程

若要开始，请打开 TunnelMAMTestApp2.xcproject 示例应用，并查看应用项目中的 AppDelegate & MicrosoftTunnelDelegate。

示例应用

✔️ 适用于 MAM 的 Microsoft Tunnel iOS SDK 示例应用下载， (打开 GitHub 站点) 。

这些示例应用可以帮助你入门并涵盖不同的方案。

MicrosoftTunnelAPI 方法

包括 MicrosoftTunnelAPI 以下方法：

  • Initialize – 检查和设置 VPN 配置、设置日志记录以及设置 MicrosoftTunnelAPI 实例。

  • Connect – 获取 MicrosoftTunnelAPI 实例并启用网络流量拦截。 如果 API 未初始化，则会显示错误。

  • Disconnect - 获取 MicrosoftTunnelAPI 实例并禁用网络流量拦截。 如果 API 未初始化，则会显示错误。

  • onTokenRequired –自选。 如果应用已与 IntuneMAM 或 MSAL 集成，则需要实现此方法 onTokenRequired 。 此方法使用 IntuneMAMSettings 和 MSAL 获取有效的身份验证令牌以连接到 Microsoft Tunnel 网关。

  • Logging – 有一些不同的日志记录类，由 k表示。 例如， kLoggingClassConnect 在 Xcode 控制台中创建日志记录输出。 这些日志记录配置键可以添加到委托配置中。 示例应用中提供了这些日志记录类的一些示例。

    • kLoggingClassInternal
    • kLoggingClassConnect
    • kLoggingClassPacket
    • kLoggingClassSocket
    • kLoggingClassHttp
    • kLoggingClassIntune
    • kLoggingClassMobileAccess
    • kLoggingSeverityDebug
    • kLoggingSeverityInfo
    • kLoggingSeverityWarn
    • kLoggingSeverityMinor
    • kLoggingSeverityMajor
    • kLoggingSeverityCrit

警告

不要在已部署的应用中使用调试密钥。 密钥可以记录并显示用户身份信息和安全数据。

在 iOS/iPadOS LOB 应用上进行日志记录

集成 SDK 不会自动启用日志记录。 开发人员必须添加适当的代码来实现日志记录委托框架并进行适当的日志记录调用。 具体实现因 SDK 和开发人员的要求而异。

开发人员应：

  • 确保记录中不包含任何客户可识别或最终用户个人数据。 他们必须遵守隐私法规。

  • 咨询并配合组织的公司/组织隐私团队。 隐私团队可以提供有关可记录的相应数据和处理敏感数据的适当方法的指导。

警告

有关日志记录和数据隐私的具体指导，请参阅 适用于 MAM 的 Microsoft Tunnel iOS SDK 隐私文档 (在 GitHub) 中打开 PDF 文件。

MAM-Tunnel 日志委托方法示例

显示 macOS 设备上 Xcode 中Microsoft Tunnel 日志委托方法示例的屏幕截图。

显示 macOS 设备上的 Xcode 中Microsoft Tunnel 日志输出示例的屏幕截图。

Microsoft Tunnel for Mobile Application Management 隐私信息

你的隐私对我们很重要。 查看以下与隐私相关的在线文档：

将 适用于 MAM 的 Microsoft Tunnel iOS SDK 集成到移动应用中时，开发人员会收集以下数据：

  • 在应用中启用Intune MAM 遥测模块

收集的数据可能包括以下方面：

  • 适用于 MAM 的 Microsoft Tunnel SDK 版本
  • Microsoft 生成的用户信息
    • 设备 ID
  • 硬件和软件信息
    • 设备制造
    • 设备型号
    • 设备 OS 版本
  • 管理员和帐户信息
    • Intune租户 ID
    • Microsoft Entra租户 ID
  • 使用情况度量：
    • VPN 初始化
    • VPN 连接和断开连接事件
  • 错误信息
    • 与 VPN 连接失败相关的错误

不会收集任何用户身份信息。

重要

作为开发人员，集成 SDK 时，在使用代码在应用程序中处理和捕获消息时，请务必不要包含任何用户可识别的数据。

已知问题

有关更多已知问题，请转到适用于 iOS/iPadOS 的适用于 MAM 的 Microsoft Tunnel - Intune管理员指南。

后续步骤

适用于 iOS/iPadOS 的适用于 MAM 的 Microsoft Tunnel - Intune管理员指南