Condividi tramite

guida per sviluppatori di Microsoft Tunnel per MAM iOS SDK

  • Articolo

Nota

Questa funzionalità è disponibile quando si aggiunge Microsoft Intune piano 2 o Microsoft Intune Suite come licenza del componente aggiuntivo. Per altre informazioni, vedere Usare le funzionalità del componente aggiuntivo Intune Suite.

La guida per sviluppatori Microsoft Tunnel per MAM iOS SDK è una risorsa per gli sviluppatori. Consente agli sviluppatori di integrare e configurare l'SDK in un'app iOS/iPadOS. Per una panoramica del Microsoft Tunnel per MAM, vedere Microsoft Tunnel per MAM per iOS/iPadOS - Intune guida all'amministratore.

Questa guida illustra diverse parti del processo di integrazione nel progetto di app Xcode, tra cui l'installazione dei framework, la configurazione del info.plist file, le impostazioni di compilazione, la condivisione delle chiavi e l'implementazione dei metodi delegati dell'SDK.

Questi componenti sono fondamentali per lo sviluppo di un'app iOS/iPadOS. Gli sviluppatori devono comprendere come spostarsi e configurare i componenti SDK. Se non si ha familiarita' con lo sviluppo di app Xcode e iOS/iPadOS, questa guida può essere utile. Offre una panoramica su dove trovare i diversi componenti SDK e su come usare questi elementi nei progetti di app.

Questa funzionalità si applica a:

  • iOS/iPadOS

Informazioni sul repository SDK

Il repository SDK include i framework seguenti. Questi framework verranno aggiunti al progetto di app in un passaggio successivo:

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

Prerequisiti

Per usare Microsoft Tunnel per MAM iOS SDK, sono necessari i prerequisiti seguenti:

  • Un computer macOS con Xcode 14.0 o versione successiva installato

  • L'app line-of-business (LOB) per iOS/iPadOS deve essere destinata a iOS/iPadOS 14.0 o versione successiva.

  • Sono disponibili due SDK GitHub che è necessario scaricare e integrare con l'app iOS in Xcode. Assicurarsi che i progetti seguenti vengano compilati correttamente prima di continuare con Microsoft Tunnel per MAM iOS SDK:

    1. Intune App SDK per iOS (apre un sito GitHub): installare almeno la versione 16.1.1.

      In questo sito esaminare anche il file Microsoft License Terms Intune App SDK per iOS.

      Per i record, conservare una copia delle condizioni di licenza. Scaricando e usando Microsoft Tunnel per MAM iOS SDK, si accettano le condizioni di licenza. Se non si accettano le condizioni di licenza, non usare il software.

    2. Microsoft Authentication Library (MSAL) ( apre un sito GitHub): installare almeno la versione 1.2.3.

  • Installare e configurare Microsoft Tunnel per MAM iOS SDK (apre un sito GitHub). Questo SDK è al centro di questo articolo.

    Importante

    Intune rilascia regolarmente gli aggiornamenti all'SDK iOS Microsoft Tunnel per MAM. Controllare regolarmente la Microsoft Tunnel per MAM iOS SDK per gli aggiornamenti. Aggiungere questi aggiornamenti nel ciclo di rilascio dello sviluppo software. Si vuole assicurarsi che le app supportano gli aggiornamenti del gateway di Microsoft Tunnel e i miglioramenti delle funzionalità.

Funzionamento dell'SDK per iOS Microsoft Tunnel per MAM

Tunnel for MAM iOS SDK consente alle app iOS/iPadOS di stabilire una connessione VPN "in-app". La connessione VPN esiste solo all'interno dell'app.

Per riepilogare, queste connessioni VPN in-app sono:

  • Connessioni VPN discrete, non a livello di dispositivo
  • Ambito solo per il livello di rete dell'applicazione

Quando un'app effettua una chiamata di rete, l'SDK intercetta la chiamata di rete e stabilisce la connessione VPN. Questa connessione VPN in-app non viene visualizzata nell'app Impostazioni nel dispositivo iOS/iPadOS.

Architettura: Tunnel per MAM iOS SDK

L'immagine seguente descrive il flusso da un'app gestita integrata correttamente con Tunnel per MAM iOS SDK:

Disegno del gateway di Microsoft Tunnel per MAM nell'architettura iOS/iPadOS in Microsoft Intune.

  1. All'avvio iniziale dell'app, viene stabilita una connessione usando Microsoft Tunnel per MAM SDK per iOS.

  2. Il tunnel ottiene un token di autenticazione del dispositivo da Microsoft Entra ID.

    Se il dispositivo ha eseguito l'accesso a un'altra app abilitata per MAM, ad esempio Outlook, Edge o l'app per dispositivi mobili Microsoft 365, il dispositivo potrebbe avere già un token di autenticazione Microsoft Entra. Se esiste già un token di autenticazione valido, viene usato il token esistente.

  3. Si verifica una connessione TCP, ovvero un handshake TLS tra il token e il server di tunnel.

  4. Se UDP è abilitato nel gateway di Microsoft Tunnel, viene stabilita una connessione al canale dati tramite DTLS. Se UDP è disabilitato, TCP stabilisce il canale dati per il gateway di tunneling.

    Per altre informazioni, vedere le note TCP e UDP nella panoramica di Microsoft Tunnel - architettura.

  5. Quando l'app per dispositivi mobili stabilisce una connessione a una risorsa aziendale locale:

    1. Un Microsoft Tunnel per MAM richieste API per connettersi alla risorsa aziendale.
    2. Viene creata e inviata una richiesta Web crittografata alla risorsa aziendale.

Attività Xcode

Questa sezione elenca e descrive le attività Xcode che è necessario completare, tra cui:

  • Aggiungere framework e librerie
  • Esaminare e aggiornare le funzionalità seguenti:
    • info.plistfile
    • Impostazioni di compilazione
    • Condivisione keychain
  • Usare gli esempi per aggiornare il progetto Xcode AppDelegate e aggiungere un file delegato di Microsoft Tunnel

Passaggio 1: Aggiungere framework e librerie

I framework seguenti includono le API e i metodi delegati necessari per comunicare con l'Intune Gateway di Microsoft Tunnel. Implementano le funzionalità VPN di Microsoft Tunnel all'interno dell'app.

Per abilitare tunnel per MAM iOS SDK, seguire questa procedura:

  1. Scaricare ed estrarre tunnel per MAM iOS SDK in una cartella in un computer macOS. Questa attività è elencata anche in Prerequisiti.

    Copiare i nove framework seguenti nella cartella dei framework di progetto dell'app Xcode:

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

  2. Nel progetto Xcode selezionare il progetto > di app Aggiungi file. Nell'esempio seguente i file vengono aggiunti a un progetto di app denominato "Flash Chat":

    Schermata che mostra come aggiungere file al progetto di app in Xcode in un dispositivo macOS.

  3. InPROJECT TARGETS (DESTINAZIONI PROGETTO>) selezionare Build Phases Embed Frameworks (Build Phases>Embed Frameworks). Aggiungere (+) tutti i nove framework:

    Screenshot che mostra l'incorporamento di framework in Xcode in un dispositivo macOS.

    L'esempio seguente mostra tutti i nove framework aggiunti:

    Screenshot che mostra tutti i framework di Microsoft Tunnel incorporati in Xcode in un dispositivo macOS.

  4. InPROJECT TARGETS (DESTINAZIONI PROGETTO>) selezionare Build PhasesLink Binary with Libraries (Collega binario> con librerie). Nell'elenco è necessario aggiungere solo il MicrosoftTunnelApi.xcframework framework. Se sono elencati altri framework, rimuoverli usando il segno meno (-):

    Screenshot che mostra come rimuovere i framework in Collegamento binario con librerie in Xcode in un dispositivo macOS.

Passaggio 2- Aggiornare il info.plist file

Nel per il info.plist progetto di app Xcode verificare le impostazioni seguenti:

  • ID bundle: assicurarsi che lo stesso ID bundle elencato nella registrazione dell'app Microsoft Entra per l'app per dispositivi mobili iOS sia lo stesso ID bundle nel progetto di app:

    Per controllare l'ID bundle:

    1. Passare aPROJECT TARGETS>General (Destinazioni progetto> generale).

    2. Selezionare IdentityBundle Identifier (Identificatore bundle diidentità>):

      Screenshot che mostra la selezione di progetto, destinazioni, generale e identità per aggiungere l'ID bundle in Xcode in un dispositivo macOS.

  • Tipi di URL: in DESTINAZIONI PROGETTO> selezionare Info.

    In Tipi di URL verificare che la $(PRODUCT_BUNDLE_IDENTIFIER) variabile sia presente. Quando è stato integrato il Intune App SDK per iOS con il progetto di app (prerequisito obbligatorio), questa variabile dovrebbe essere stata creata.

    Se la variabile non è presente, è necessario aggiungerla:

    1. Usando Intune App SDK per iOS (prerequisito obbligatorio), creare una info.plist proprietà Array e denominarla Schemi URL sottoposti a query.

      Aggiungere gli elementi stringa elencati nella guida per sviluppatori Intune App SDK per iOS - Passaggio 5. Questo passaggio crea gli schemi DI URL di MAM SDK Intune.

      L'esempio seguente mostra info.plist usando schemi URL sottoposti a query:

      Screenshot che mostra la selezione di progetti, destinazioni, informazioni, schemi URL sottoposti a query in Xcode in un dispositivo macOS.

    2. Aggiungere la $(PRODUCT_BUNDLE_IDENTIFIER) variabile .

      Nell'esempio seguente viene illustrata la $(PRODUCT_BUNDLE_IDENTIFIER) variabile in Tipi di URL:

      Screenshot che mostra la selezione di progetto, destinazioni, informazioni, tipi di URL in Xcode in un dispositivo macOS.

  • IntuneMAMSettings: verificare che le impostazioni MSAL seguenti siano configurate con i valori di registrazione dell'app Microsoft Entra appropriati:

    1. Passare aPROJECT TARGETS Info (Informazioni sulleDESTINAZIONI>DEL PROGETTO>).

    2. Selezionare IntuneMAMSettings. Confermare le impostazioni:

      • ADALAuthority: immettere l'ID tenant Microsoft Entra, ad esempio https://login.microsoftonline.com/USE_YOUR_ Directory (tenant) ID.
      • ADALClientId: immettere l'ID client dell'applicazione.
      • ADALRedirectUri: immettere msauth.$(PRODUCT_BUNDLE_IDENTIFIER):/auth.

    Quando è stato integrato il Intune App SDK per iOS con il progetto di app (prerequisito obbligatorio), queste impostazioni devono essere state configurate.

    Se queste impostazioni non sono configurate, è necessario configurarle. Per creare la proprietà IntuneMAMSettings info.plist Dictionary e le stringhe associate della libreria di autenticazione Microsoft, seguire la guida per sviluppatori Intune App SDK per iOS (prerequisito obbligatorio) in Configurare le impostazioni MSAL per Intune le indicazioni di App SDK.

    L'esempio seguente mostra questi valori configurati:

    Screenshot che mostra la selezione di progetto, destinazioni, informazioni, IntuneMAMSetting in Xcode in un dispositivo macOS.

Passaggio 3 - Disattivare Bitcode

  1. Passare aPROJECT TARGETSBuild settings (Impostazioni di compilazione di PROJECT> TARGETS>).
  2. Selezionare Opzioni> di compilazioneAbilita codice bit.
  3. Selezionare No.

Screenshot che mostra la selezione di progetto, destinazioni, impostazioni di compilazione, opzioni di compilazione e disabilitazione del codice bit in Xcode in un dispositivo macOS.

Passaggio 4 - Aggiungere la condivisione del portachiava

La condivisione del portachiava può essere presente o meno nel progetto di app. Se non è presente, aggiungerlo:

  1. Passare a Project TargetsSigning & Capabilities (Funzionalità di firma di PROJECT>TARGETS>).
  2. Selezionare Condivisione keychain.
  3. Nell'elenco keychain Gruppi aggiungere (+) com.microsoft.workplacejoin.

Screenshot che mostra la selezione di progetto, destinazioni, funzionalità di firma &, condivisione keychain e aggiunta di un gruppo keychain in Xcode in un dispositivo macOS.

Passaggio 5: Integrare l'SDK con l'app

✔️ Usare l'app TunnelMAMTestApp2.xcproject di esempio.

A seconda dell'app LOB e del relativo scopo di implementazione/scopo, l'uso di MicrosoftTunnelApi può variare. Esistono alcune funzionalità principali da conoscere durante l'integrazione dell'SDK con l'app:

  • Tutte le interazioni con Microsoft Tunnel per MAM iOS SDK vengono gestite tramite un MicrosoftTunnelAPI oggetto singleton.
  • L'oggetto MicrosoftTunnelAPI interagisce con l'app usando un delegato che implementa un'interfaccia MicrosoftTunnelDelegate . 

Per informazioni su come scrivere il delegato di Microsoft Tunnel e su come inizializzare MicrosoftTunnelAPI, usare il Microsoft Tunnel per MAM app di esempio di iOS SDK (apre un sito GitHub).

Nelle app di esempio, il progetto Xcode AppDelegate mostra:

  • Come gestire i callback dell'URL MSAL
  • Come avviare il processo di registrazione e inizializzazione necessario per il tunnel

Per iniziare, aprire l'app TunnelMAMTestApp2.xcproject di esempio e esaminare AppDelegate & MicrosoftTunnelDelegate nel progetto di app.

App di esempio

✔️ Scaricare in Microsoft Tunnel per MAM app di esempio di iOS SDK (apre un sito GitHub).

Queste app di esempio consentono di iniziare a gestire scenari diversi.

Metodi di MicrosoftTunnelAPI

include MicrosoftTunnelAPI i metodi seguenti:

  • Initialize : controlla e imposta le configurazioni VPN, configura la registrazione e configura l'istanza MicrosoftTunnelAPI .

  • Connect : ottiene l'istanza e abilita l'intercettazione MicrosoftTunnelAPI del traffico di rete. Se l'API non è inizializzata, viene visualizzato un errore.

  • Disconnect - Ottiene l'istanza e disabilita l'intercettazione MicrosoftTunnelAPI del traffico di rete. Se l'API non è inizializzata, viene visualizzato un errore.

  • onTokenRequired –Opzionale. Se l'app si integra già con IntuneMAM o MSAL, è necessario implementare questo onTokenRequired metodo. Questo metodo usa IntuneMAMSettings e MSAL per ottenere un token di autenticazione valido per connettersi al gateway di Microsoft Tunnel.

  • Logging : esistono alcune classi di registrazione diverse, indicate da k. Ad esempio, kLoggingClassConnect crea l'output di registrazione nella console Xcode. Queste chiavi di configurazione di registrazione possono essere aggiunte alla configurazione del delegato. Esistono alcuni esempi di queste classi di registrazione nelle app di esempio.

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

Avviso

Non usare le chiavi di debug nelle app distribuite. Le chiavi possono registrare e visualizzare informazioni identificabili dall'utente e dati di sicurezza.

Accesso alle app lob iOS/iPadOS

L'integrazione dell'SDK non abilita automaticamente la registrazione. Lo sviluppatore deve aggiungere il codice appropriato per implementare il framework del delegato di registrazione ed effettuare le chiamate di registrazione appropriate. L'implementazione specifica varia a seconda dell'SDK e dei requisiti dello sviluppatore.

Lo sviluppatore deve:

  • Assicurarsi che non includano dati personali identificabili o dell'utente finale nella registrazione. Devono rispettare le normative sulla privacy.

  • Consultare e collaborare con il team per la privacy aziendale/aziendale dell'organizzazione. Il team per la privacy può fornire indicazioni sui dati appropriati che possono essere registrati e sui modi appropriati per gestire i dati sensibili.

Avviso

Consultare la documentazione sulla privacy di Microsoft Tunnel per MAM iOS SDK (apre un file PDF in GitHub) per indicazioni specifiche sulla registrazione e la privacy dei dati.

MAM-Tunnel esempio di metodo delegato del log

Screenshot che mostra un metodo delegato di log di Microsoft Tunnel di esempio in Xcode in un dispositivo macOS.

Screenshot che mostra un output di log di Microsoft Tunnel di esempio in Xcode in un dispositivo macOS.

Informazioni sulla privacy di Microsoft Tunnel for Mobile Application Management

La tua privacy è importante per noi. Esaminare la documentazione online relativa alla privacy seguente:

Quando si integra l'SDK Microsoft Tunnel per MAM iOS nelle app per dispositivi mobili, quando uno sviluppatore raccoglie i dati seguenti:

  • Abilita il modulo di telemetria MAM Intune nell'app

I dati raccolti possono includere le aree seguenti:

  • versione dell'SDK Microsoft Tunnel per MAM
  • Informazioni utente generate da Microsoft
    • ID dispositivo
  • Informazioni hardware e software
    • Marca del dispositivo
    • Modello dispositivo
    • Versione del sistema operativo del dispositivo
  • Amministrazione e informazioni sull'account
    • ID tenant Intune
    • MICROSOFT ENTRA ID tenant
  • Misurazione dell'utilizzo:
    • Inizializzazione VPN
    • Eventi di connessione e disconnessione VPN
  • Informazioni sull'errore
    • Errori correlati a un errore di connessione VPN

Non vengono raccolte informazioni identificabili dall'utente.

Importante

In qualità di sviluppatore, quando si integra l'SDK è importante non includere dati identificabili dall'utente quando si usa il codice per indirizzare e acquisire messaggi nell'applicazione.

Problemi noti

Per problemi più noti, passare alla guida Microsoft Tunnel per MAM per iOS/iPadOS - Intune admin.

Passaggi successivi

Microsoft Tunnel per MAM per iOS/iPadOS - Guida all'amministratore Intune