共用方式為

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

  • 發行項

注意事項

當您將 Microsoft Intune 方案 2 或 Microsoft Intune Suite 新增為附加元件授權時，即可使用此功能。 如需詳細資訊，請參閱使用 Intune Suite 附加元件功能。

適用於 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 app SDK for iOS (會開啟 GitHub 網站) ：至少安裝 16.1.1 版。

      在此網站中，也請檢閱 Microsoft 授權條款 Intune 適用於 iOS 的 App 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通道閘道閘道更新和功能增強功能。

適用於 MAM 的 Microsoft Tunnel iOS SDK 的運作方式

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

總而言之，這些應用程式內 VPN 連線包括：

  • 離散，而不是裝置層級 VPN 連線
  • 僅限應用程式網路層

當應用程式進行網路呼叫時，SDK 會攔截網路呼叫並建立 VPN 連線。 此應用程式內 VPN 連線不會顯示在 iOS/iPadOS 裝置上的 [設定] 應用程式中。

架構：MAM iOS SDK 的通道

下圖說明成功與適用於 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 Connect，這是令牌與通道伺服器之間的 TLS 交握。

  4. 如果在Microsoft通道閘道閘道關上啟用 UDP，則會使用 DTLS 建立數據通道連線。 如果停用 UDP，TCP 就會建立通道閘道閘道。

    如需詳細資訊，請移至 Microsoft Tunnel 概觀 - 架構中的 TCP 和 UDP 附注。

  5. 當行動應用程式連線到內部部署公司資源時：

    1. 聯機到公司資源的 適用於 MAM 的 Microsoft Tunnel API 要求。
    2. 系統會建立加密的 Web 要求，並將其傳送至公司資源。

Xcode 工作

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

  • 新增架構和連結庫
  • 檢閱並更新下列功能：
    • info.plist檔
    • 組建設定
    • 金鑰鏈共用
  • 使用範例來更新 Xcode AppDelegate 專案，並新增 Microsoft Tunnel 委派檔案

步驟 1 - 新增架構和連結庫

下列架構包含與 Intune Microsoft Tunnel 閘道通訊所需的 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 Tunnel 架構。

  4. 在 [項目>目標] 中>，選取 [建置階段連結二進位檔與連結庫]。 在清單中，只 MicrosoftTunnelApi.xcframework 應新增架構。 如果列出其他架構，請使用減號 () - 加以移除：

    顯示如何在 macOS 裝置上使用 Xcode 連結二進位檔與連結庫中的架構的螢幕快照。

步驟 2 - 更新 info.plist 檔案

info.plist在 Xcode 應用程式專案的 中，確認下列設定：

  • 套件組合標識碼：確定iOS行動應用程式的 Microsoft Entra 應用程式註冊中所列的相同套件組合識別碼，與您應用程式專案中的套件組合識別元相同：

    若要檢查套件組合識別碼：

    1. 移至 [項目>目標>一般]。

    2. 選 取 [身分識別>套件組合標識符]：

      顯示在macOS裝置上選取專案、目標、一般和身分識別，以在 Xcode 中新增套件組合標識碼的螢幕快照。

  • URL 類型：在 [項目>目標] 中，選取 [ 資訊]。

    在 [URL 類型] 中 $(PRODUCT_BUNDLE_IDENTIFIER) ，確認變數存在。 當您將 Intune App SDK for iOS 與應用程式專案整合 (必要的必要條件) 時，應該已建立此變數。

    如果變數不存在，則您需要新增它：

    1. 使用 Intune App SDK for iOS (必要的必要條件) ，建立 Arrayinfo.plist 屬性並將它命名為 Queried URL 配置。

      新增 Intune App SDK for iOS 開發人員指南 – 步驟 5 中所列的字串專案。 此步驟會建立 Intune MAM SDK URL 配置。

      下列範例顯示使用 Queried URL 配置的 info.plist：

      顯示在macOS裝置上選取 Xcode 中專案、目標、資訊、查詢URL配置值的螢幕快照。

    2. $(PRODUCT_BUNDLE_IDENTIFIER)新增變數。

      下列範例顯示 $(PRODUCT_BUNDLE_IDENTIFIER)URL 類型中的 變數：

      顯示在macOS裝置上選取 Xcode 中專案、目標、資訊、URL 類型的螢幕快照。

  • IntuneMAMSettings：確認已使用適當的 Microsoft Entra 應用程式註冊值來設定下列 MSAL 設定：

    1. 移至 [項目>目標>資訊]。

    2. 選取 [IntuneMAMSettings]。 確認您的設定：

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

    當您將 Intune App SDK for iOS 與應用程式專案整合 (必要的必要條件) 時，應該已設定這些設定。

    如果未設定這些設定，則您必須加以設定。 若要建立 IntuneMAMSettings info.plist Dictionary 屬性和相關聯的 Microsoft 驗證連結庫字串，請遵循 Intune App SDK for iOS (設定 Intune App SDK 的 MSAL 設定中的必要條件) 開發人員指南。

    下列範例顯示已設定的這些值：

    顯示在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 記錄委派方法範例

此螢幕快照顯示範例Microsoft macOS裝置上 Xcode 中的通道記錄委派方法。

此螢幕快照顯示範例Microsoft macOS裝置上 Xcode 中的通道記錄輸出。

行動應用程式管理隱私權資訊Microsoft通道

您的隱私權對我們很重要。 檢閱下列隱私權相關的在線檔：

將 適用於 MAM 的 Microsoft Tunnel iOS SDK 整合到行動應用程式時，開發人員會收集下列資料：

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

收集的資料可能包含下列區域：

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

不會收集任何使用者標識資訊。

重要事項

身為開發人員，在整合 SDK 時，請務必不要在使用程式代碼來處理和擷取應用程式中的訊息時包含任何使用者可識別的數據。

已知問題

如需更多已知問題，請移至 iOS/iPadOS 的 適用於 MAM 的 Microsoft Tunnel - Intune 系統管理員指南。

後續步驟

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