適用於 MAM 的 Microsoft Tunnel iOS SDK 開發者指南

適用於 MAM 的 Microsoft Tunnel iOS SDK 開發者指南是開發者的資源。 它幫助開發者將 SDK 整合並配置到 iOS/iPadOS 應用程式中。 關於 適用於 MAM 的 Microsoft Tunnel 的概述，請參閱 適用於 MAM 的 Microsoft Tunnel for iOS/iPadOS - 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 iOS 版 App SDK (會開啟一個 GitHub 網站) ：至少安裝 16.1.1 版本。

    在此網站，您也可以參考 Microsoft 授權條款 Intune App SDK for iOS 檔案。

    為了記錄，請保留授權條款的副本。 下載並使用 適用於 MAM 的 Microsoft Tunnel iOS SDK 即表示您同意授權條款。 如果你不接受授權條款，那就不要使用這套軟體。

    1. 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 Gateway 的更新和功能增強。

適用於 MAM 的 Microsoft Tunnel iOS SDK 如何運作

MAM iOS SDK 的隧道功能讓 iOS/iPadOS 應用程式能建立「應用程式內」的 VPN 連線。 VPN 連線只存在於應用程式內。

總結來說，這些應用程式內的 VPN 連線包括：

  • 獨立的 VPN 連線，而非裝置層級的 VPN 連線
  • 僅限於應用網路層

當應用程式進行網路通話時，SDK 會攔截該網路通話並建立 VPN 連線。 這個應用程式內的 VPN 連線在 iOS/iPadOS 裝置的設定應用程式中並未顯示。

架構：MAM iOS SDK 隧道

下圖描述了一個已成功整合 Tunnel for MAM iOS SDK 的受管理應用程式流程：

Microsoft Intune 中 Microsoft 隧道閘道器繪製於 iOS/iPadOS 架構上的 MAM。

  1. 應用程式初次啟動時，會使用 iOS 版 適用於 MAM 的 Microsoft Tunnel SDK 建立連線。

  2. 隧道會從 Microsoft Entra ID 取得裝置認證令牌。

    如果裝置登入了另一個支援 MAM 的應用程式，例如 Microsoft Outlook、Microsoft Edge 或 Microsoft 365 行動應用程式，那麼該裝置可能已經擁有 Microsoft Entra 認證憑證。 如果已有有效的認證令牌存在，則會使用現有的令牌。

  3. 會發生 TCP 連線，這是憑證與隧道伺服器之間的 TLS 握手。

  4. 若 Microsoft 隧道閘道啟用 UDP，則會使用 DTLS 建立資料通道連線。 若 UDP 被停用，TCP 會建立資料通道至隧道閘道。

    更多資訊請參閱 Microsoft 隧道概述 - 架構中的 TCP 與 UDP 說明。

  5. 當行動應用程式連接到本地企業資源時：

    1. 適用於 MAM 的 Microsoft Tunnel API 請求連接公司資源。
    2. 一個加密的網路請求會被建立並傳送給企業資源。

Xcode 任務

本節列出並描述您必須完成的 Xcode 任務，包括：

  • 新增框架與函式庫
  • 檢視並更新以下功能：
    • info.plist檔案
    • 建構設定
    • 鑰匙圈共享
  • 利用範例更新 Xcode AppDelegate 專案並新增 Microsoft Tunnel 代理檔

步驟 1 - 新增框架與函式庫

以下框架包含與 Intune Microsoft 隧道閘道器通訊所需的 API 與委派方法。 他們在應用程式中實作了 Microsoft Tunnel VPN 的功能。

要啟用 MAM iOS SDK 隧道，請使用以下步驟：

  1. 下載並解壓 MAM iOS SDK 隧道到 macOS 電腦上的資料夾。 此任務也列於 前置條件中。

    將以下九個框架複製到 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 框架的畫面。

    以下範例展示了新增的全部九個框架：

    截圖顯示 macOS 裝置上 Xcode 內嵌的所有 Microsoft 隧道框架。

  4. 在 專案>目標中，選擇「建立階段 連結>二進位與函式庫」。 在清單中，應該只 MicrosoftTunnelApi.xcframework 加入框架。 若列出其他框架，請使用減 () - 移除：

    這張截圖展示了如何在 macOS 裝置上用 Xcode 的函式庫移除 Link Binary 中的框架。

步驟 2 - 更新 info.plist 檔案

在 info.plist For the Xcode 應用程式專案中，確認以下設定：

  • Bundle ID：確保 iOS 行動應用程式 Microsoft Entra App 註冊中列出的 Bundle ID 與你的應用程式專案中的 Bundle ID 相同：

    要檢查套件 ID：

    1. 請前往 PROJECT>TARGETS>General。

    2. 選擇 身份>組合識別碼：

      截圖顯示在 macOS 裝置上選擇專案、目標、通用和身份以加入 bundle ID 的 Xcode。

  • URL 類型：在 專案>目標中，選擇 資訊。

    在 URL 類型中，確認 $(PRODUCT_BUNDLE_IDENTIFIER) 變數存在。 當你將 Intune App SDK for iOS 整合到應用程式專案中時， (必須的前置條件) ，這個變數應該已經建立。

    如果變數不存在，那你就需要加入它：

    1. 使用 Intune App SDK for iOS () 的前提條件，建立一個info.plist陣列屬性並命名為 Queried URL Schemes。

      把 Build the SDK 步驟 5 中列出的字串項目 加入你的行動應用程式。 此步驟建立 Intune MAM SDK URL 方案。

      以下範例展示了使用 Queried URL Schemes 製作的 info.plist：

      截圖顯示在 macOS 裝置上選擇專案、目標、資訊、查詢的 URL 配置和數值。

    2. 加入變 $(PRODUCT_BUNDLE_IDENTIFIER) 數。

      以下範例展示了 $(PRODUCT_BUNDLE_IDENTIFIER)URL Types 中的變數：

      截圖顯示在 macOS 裝置上選擇專案、目標、資訊、URL 類型。

  • IntuneMAMSettings：確認以下 MSAL 設定是否已設定為適當的 Microsoft Entra 應用程式註冊值：

    1. 請前往 PROJECT>TARGETS>資訊。

    2. 選擇 IntuneMAMSettings。 確認你的設定：

      • ADALAuthority輸入 Microsoft Entra 租戶 ID，例如 https://login.microsoftonline.com/USE_YOUR_ Directory (tenant) ID。
      • ADALClientId： 輸入應用程式客戶端 ID。
      • ADALRedirectUri：進入 msauth.$(PRODUCT_BUNDLE_IDENTIFIER):/auth。

    當你將 iOS 版 Intune App SDK 與你的應用程式專案整合 (必須的前置條件) 時，這些設定應該已經被設定好了。

    如果這些設定沒設定好，那你就需要重新設定。 要建立 IntuneMAMSettings info.plist 字典屬性及相關的 Microsoft 認證函式庫字串，請依照 iOS 版 Intune App SDK (Configure MSAL settings for Intune App SDK 開發者指南) 必修的先決條件。

    以下範例展示了這些數值的配置：

    截圖顯示在 macOS 裝置上選擇專案、目標、資訊，以及 IntuneMAMSetting 的過程。

步驟 3 - 關閉 Bitcode

  1. 前往專案>目標>建置設定。
  2. 選擇 建置選項>啟用位元碼。
  3. 選擇「不」。

截圖顯示在 macOS 裝置上選取專案、目標、建置設定、建置選項，以及在 Xcode 中停用位元碼。

步驟四 - 新增鑰匙圈共享功能

鑰匙圈共享可能會在應用程式專案中出現。 如果沒有，請補充：

  1. 請前往 PROJECT>TARGETS>簽署 & 能力。
  2. 選擇 鑰匙圈共享。
  3. 在 鑰匙圈群組 列表中，新增 (+) com.microsoft.workplacejoin。

截圖顯示在 macOS 裝置上 Xcode 中選擇專案、目標、簽署 & 功能、鑰匙圈共享，以及新增鑰匙圈群組。

步驟 5 - 將 SDK 整合到你的應用程式中

✔️ 使用 TunnelMAMTestApp2.xcproject 範例應用程式。

根據 LOB 應用程式及其實作/預期用途，該功能的 MicrosoftTunnelApi 使用方式會有所不同。 在整合 SDK 與應用程式時，有一些核心功能需要了解：

  • 與 適用於 MAM 的 Microsoft Tunnel iOS SDK 的所有互動皆透過MicrosoftTunnelAPI單例物件處理。
  • 物件 MicrosoftTunnelAPI 透過一個代理與應用程式互動，該代理實作介面 MicrosoftTunnelDelegate 。 

要了解如何撰寫 Microsoft 隧道代理及初始化，MicrosoftTunnelAPI請使用 適用於 MAM 的 Microsoft Tunnel iOS SDK 範例應用程式 (開啟 GitHub 網站) 。

在範例應用程式中，Xcode 專案 AppDelegate 顯示：

  • 如何處理 MSAL URL 回撥
  • 如何開始隧道所需的註冊與初始化流程

要開始，打開 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 隧道閘道器。

  • 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 log delegate 方法範例

截圖顯示 macOS 裝置上 Xcode 中 Microsoft 隧道日誌代理方法的範例。

截圖顯示 macOS 裝置上 Xcode 中 Microsoft 隧道日誌的範例輸出。

Microsoft Tunnel 用於行動應用程式管理的隱私資訊

您的隱私對我們非常重要。 請檢視以下與隱私相關的線上文件：

當 適用於 MAM 的 Microsoft Tunnel iOS SDK 整合進行動應用程式時，開發者會收集以下資料：

  • 啟用應用程式中的 Intune MAM 遙測模組

所收集的資料可能包括以下領域：

  • 適用於 MAM 的 Microsoft Tunnel SDK 版本
  • Microsoft 產生的使用者資訊
    • 裝置識別碼
  • 硬體與軟體資訊
    • 裝置製造商
    • 裝置型號
    • 裝置作業系統版本
  • 管理員與帳號資訊
    • Intune 租戶識別碼
    • Microsoft Entra tenant ID
  • 使用量測量：
    • VPN 初始化
    • VPN 連線與斷線事件
  • 錯誤資訊
    • 與 VPN 連線失敗相關的錯誤

不收集可識別用戶的資訊。

重要事項

作為開發者，整合 SDK 時，使用程式碼來處理和捕捉應用程式訊息時，務必不包含任何可識別的使用者資料。

已知問題

欲知更多已知問題，請參閱 適用於 MAM 的 Microsoft Tunnel for iOS/iPadOS - Intune 管理員指南。

後續步驟

適用於 MAM 的 Microsoft Tunnel for iOS/iPadOS - Intune 管理員指南

  • Last updated on