Intune App SDK per Android - Introduzione a MAM

Microsoft Intune App SDK per Android consente di incorporare i criteri di protezione delle app di Intune (noti anche come criteri APP o MAM) nell'app Java/Kotlin Android nativa. Un'applicazione gestita da Intune è integrata con Intune App SDK. Gli amministratori di Intune possono distribuire facilmente i criteri di protezione delle app nell'app gestita da Intune quando Intune gestisce attivamente l'app.

Fase 3: Introduzione a MAM

Obiettivi di fase

• Scaricare Intune App SDK.
• Informazioni sui file inclusi in Intune App SDK.
• Fare riferimento a Intune App SDK nell'applicazione.
• Configurare il plug-in di compilazione dell'app di Intune oppure usare lo strumento di compilazione da riga di comando.
• Verificare che Intune App SDK sia incluso correttamente nella compilazione.

Background

Ora che l'applicazione ha integrato correttamente MSAL, è il momento di scaricare Intune App SDK e includerlo nel processo di compilazione dell'applicazione.

Gran parte dell'integrazione di Intune App SDK sta sostituendo le classi Android standard e le chiamate ai metodi con le versioni di Intune di tali classi e chiamate al metodo. L'SDK include strumenti di compilazione che consentono di eseguire automaticamente la maggior parte di queste sostituzioni. Per altre informazioni su questa logica di sostituzione, vedere la sezione sostituzioni di classi e metodidell'appendice.

Scaricare Intune App SDK

Per scaricare l'SDK, vedere Scaricare i file SDK.

Che cosa c'è nell'SDK?

Intune App SDK è costituito dai file seguenti:

• Microsoft.Intune.MAM.SDK.aar: componenti SDK, ad eccezione dei file JAR della libreria di supporto.
• com.microsoft.intune.mam.build.jar: plug-in Gradle, che facilita l'integrazione dell'SDK.
• CHANGELOG.md: fornisce un record delle modifiche apportate in ogni versione dell'SDK.
• THIRDPARTYNOTICES.TXT: nota di attribuzione che riconosce codice di terze parti e/o del sistema operativo che verrà compilato nell'app.
• Microsoft.Intune.MAM.SDK.DownlevelStubs.aar: questo AAR contiene stub per le classi di sistema Android presenti solo nei dispositivi più recenti, ma a cui fanno riferimento i metodi in MAMActivity. I dispositivi più recenti ignorano queste classi stub. Questo AAR è necessario solo se l'app esegue reflection sulle classi derivate da MAMActivitye la maggior parte delle app non deve includerla. L'AAR contiene regole ProGuard per escludere tutte le relative classi.

Riferimento alle librerie di app di Intune

Intune App SDK è una libreria Android standard senza dipendenze esterne. Microsoft.Intune.MAM.SDK.aar contiene entrambe le interfacce necessarie per abilitare i criteri di protezione delle app e il codice necessario per interagire con l'app Portale aziendale di Microsoft Intune.

Android Studio

Microsoft.Intune.MAM.SDK.aar deve essere specificato come riferimento alla libreria Android. Per aggiungere questa dipendenza alla compilazione, seguire Aggiungere il file AAR o JAR come dipendenza dalla documentazione di Android.

Visual Studio

Il pacchetto Intune App SDK per .NET MAUI - Android NuGet deve essere aggiunto come dipendenza.

Seguire il processo per Installare e gestire pacchetti in Visual Studio usando Gestione pacchetti NuGet.

Microsoft.Intune.MAM.SDK.aar è associato per creare riferimenti C# con ambito allo spazio dei Microsoft.Intune.Mam nomi.

ProGuard

L'applicazione potrebbe già usare ProGuard (o qualsiasi altro meccanismo di compattazione/offuscamento) come passaggio di compilazione. Intune App SDK include regole di configurazione ProGuard che devono essere incluse nel passaggio di compilazione. Inclusione di . AAR nella compilazione, come descritto in precedenza, integra automaticamente la configurazione dell'SDK nel passaggio ProGuard, in modo da mantenere i file di classe necessari. Se è stato incluso correttamente l'oggetto . AAR, non sono necessarie altre modifiche.

Microsoft Authentication Library (MSAL) viene fornito con la propria configurazione ProGuard. Se l'app integra MSAL, per altre informazioni, vedere la documentazione di MSAL .

Strumenti di compilazione

L'SDK fornisce strumenti di compilazione (un plug-in per le compilazioni Gradle, destinazioni per le compilazioni .NET e uno strumento da riga di comando) che eseguono automaticamente le sostituzioni MAM. Questi strumenti trasformano i file di classe generati dalla compilazione Java; non modificano il codice sorgente originale. È necessario usare il plug-in Gradle, il pacchetto NuGet .NET o lo strumento da riga di comando.

Gli strumenti di compilazione da soli non sono sufficienti per integrare completamente l'applicazione. Gli strumenti eseguono solo sostituzioni di classi e metodi . Non eseguono integrazioni SDK più complesse, ad esempio multi-identità, registrazione per i criteri di protezione delle app, criteri per limitare il trasferimento dei dati tra app e dispositivi o posizioni di archiviazione cloud o configurazione MSAL, che deve essere completata prima che l'app sia completamente abilitata per Intune. Esaminare attentamente il resto di questa documentazione per i punti di integrazione rilevanti per l'app.

Impatto sul debug

Gli strumenti di compilazione eseguono sostituzioni dopo la compilazione, che modificheranno alcuni nomi di metodo. Di conseguenza, il debug dei punti di interruzione impostati sui nomi dei metodi potrebbe essere interessato e non essere interrotto come previsto. I punti di interruzione del numero di riga non sono interessati.

MAM nello stack

Poiché l'integrazione di Intune App SDK si basa principalmente sulle sostituzioni di classi e metodi, si inizierà a visualizzare mam tutte le tracce dello stack. Quando l'app non ha un account destinato ai criteri di protezione delle app, tutto questo codice MAM è inattiva: MAMActivity funzionerà come , onMAMCreate funzionerà allo stesso ActivityonCreatemodo di e così via. Ogni volta che viene visualizzato mam in uno stack, controllare prima di tutto:

• L'account è destinato ai criteri di protezione delle app?
• Il portale aziendale di Intune è installato?

A meno che la risposta a entrambi sia "sì", il codice MAM funge da semplice pass-through.

Quale strumento è necessario?

Se si compila l'app con Gradle, vedere Integrazione con il plug-in di compilazione Gradle

Se si compila l'app con .NET MAUI, vedere Integrazione con le destinazioni MAUI .NET.

Se si compila l'app con nessuno dei due elementi precedenti, vedere Integrazione con lo strumento da riga di comando.

Integrazione con il plug-in di compilazione Gradle

Il plug-in Intune App SDK viene distribuito come parte dell'SDK come GradlePlugin/com.microsoft.intune.mam.build.jar.

Affinché il plug-in venga riconosciuto da Gradle, è necessario aggiungerlo al buildscript classpath. Il plug-in dipende da Javassist, che deve essere aggiunto anche. Per altre informazioni sulla dipendenza Javassist, vedere Dipendenze.

Per aggiungerli al classpath, aggiungere quanto segue alla radice build.gradle:

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "org.javassist:javassist:3.29.2-GA"
        classpath files("$PATH_TO_MAM_SDK/GradlePlugin/com.microsoft.intune.mam.build.jar")
    }
}

Quindi, per applicare il plug-in, aggiungere quanto segue al file per l'app build.gradle e i moduli di funzionalità dinamici:

apply plugin: 'com.microsoft.intune.mam'

Per impostazione predefinita, il plug-in opera su project dipendenze e librerie esterne. La compilazione dei test non è interessata.

Dipendenze

Il plug-in Gradle ha una dipendenza da Javassist, che deve essere reso disponibile per la risoluzione delle dipendenze di Gradle. Javassist viene usato esclusivamente in fase di compilazione quando si esegue il plug-in e non verrà aggiunto codice Javassist all'app.

Inoltre, quando si usa MAM SDK 8.0.0+, è necessario assicurarsi che nella configurazione di Gradle sia impostato quanto segue:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Esclusioni

È possibile che vengano fornite configurazioni aggiuntive per escludere dalla riscrittura componenti specifici dell'app. Le esclusioni sono prevalentemente utili per i componenti che non sono rilevanti per MAM (ad esempio, non gestiscono o visualizzano dati aziendali).

Le esclusioni possono essere configurate per ambiti diversi:

• excludeProjects consente di escludere un elenco di progetti Gradle. Queste esclusioni sono utili per i progetti che non si interfacciano con le librerie Android o le API di sistema e/o non gestiscono i dati aziendali. Ad esempio, un progetto che contiene esclusivamente codice nativo per l'esecuzione di operazioni di rete di basso livello potrebbe essere un buon candidato. Se un progetto si interfaccia ampiamente con le librerie Android o le API di sistema, è necessario evitare queste esclusioni.
• excludeClasses consente di escludere un elenco di classi. Queste esclusioni sono utili per le classi che non gestiscono o presentano dati aziendali. Ad esempio, le schermate iniziali e gli onboarding Activitysono buoni candidati. Si noti che una classe non può essere esclusa se viene elaborata una delle relative superclassi.
• excludeVariants consente di escludere le varianti di progetto. Queste esclusioni possono fare riferimento a un nome variante completo o a un singolo sapore. Sono particolarmente utili se vuoi creare un sapore non MAM della tua app. Ad esempio, se l'app ha tipi di debug compilazione e release con le versioni {noMAM, MAM} e {mock, production} è possibile specificare quanto segue:
  • noMAM per escludere tutte le varianti con il sapore noMAM o
  • noMAMMockDebug per escludere solo la variante esatta.

Esempio di build.gradle parziale con esclusioni

apply plugin: 'com.microsoft.intune.mam'

dependencies {
    implementation project(':product:FooLib')
    implementation project(':product:foo-project')
    implementation "com.microsoft.bar:baz:1.0.0"

    // Include the MAM SDK
    implementation files("$PATH_TO_MAM_SDK/Microsoft.Intune.MAM.SDK.aar")
}
intunemam {
    excludeProjects = [':product:FooLib']
    excludeClasses = ['com.contoso.SplashActivity']
    excludeVariants = ['noMAM']
}

Ciò avrebbe gli effetti seguenti:

• :product:FooLib non viene riscritto perché è incluso in excludeProjects
• :product:foo-project viene riscritto, ad eccezione di com.contoso.SplashActivity, che viene ignorato perché è in excludeClasses
• com.microsoft.bar:baz.1.0.0 viene riscritto perché tutte le librerie esterne sono incluse per l'elaborazione.
• Le varianti con il noMAM sapore non vengono riscritte.

Creazione di report

Il plug-in di compilazione può generare un report html delle modifiche apportate. Per richiedere la generazione di questo report, specificare report = true nel intunemam blocco di configurazione. Se generato, il report verrà scritto outputs/logs nella directory di compilazione.

intunemam {
    report = true
}

Verifica

Il plug-in di compilazione può eseguire una verifica aggiuntiva per cercare possibili errori nelle classi di elaborazione. Questi controlli consentono di evitare potenziali errori di runtime generati da plug-in.

Per richiedere la verifica viene eseguita nella compilazione, specificare verify = true nel blocco di intunemam configurazione. Ciò può aggiungere alcuni secondi al tempo impiegato dall'attività del plug-in.

intunemam {
    verify = true
}

In genere, un errore di verifica rappresenta un bug nel plug-in di compilazione. Per assistenza in caso di errore, inoltrare il problema con il supporto tecnico Microsoft. Se non si ha un contratto di supporto Microsoft, aprire un problema di GitHub.

Compilazioni incrementali

Per abilitare il supporto per la compilazione incrementale, specificare incremental = true nel intunemam blocco di configurazione. Questa funzionalità aumenta le prestazioni di compilazione elaborando solo i file di input modificati. La configurazione predefinita per incremental è false.

intunemam {
    incremental = true
}

Configurazione del modulo di funzionalità dinamica

I moduli di funzionalità dinamica vengono compilati separatamente dal progetto di app. Di conseguenza, anche i moduli di funzionalità dinamica devono applicare il plug-in di compilazione Gradle.

A causa di limitazioni tecniche nelle API usate dal plug-in Gradle, le classi di app devono essere rielaborato durante la trasformazione delle classi del modulo di funzionalità dinamiche. Per garantire che questa operazione possa essere eseguita, tutti i moduli di funzionalità devono essere configurati con le stesse impostazioni dell'app per cui è progettata.

Ad esempio, se un'app esclude una classe, anche il modulo di funzionalità dinamica deve escludere tale classe.

Integrazione con le destinazioni MAUI .NET

Le destinazioni di Intune App SDK vengono distribuite come parte dell'SDK come Microsoft.Intune.Maui.Essentials.android.targets.

Le destinazioni verranno importate automaticamente nell'applicazione in fase di compilazione dopo l'aggiunta del pacchetto Intune App SDK per .NET MAUI - Android NuGet.

Integrazione con lo strumento di compilazione della riga di comando

Lo strumento di compilazione da riga di comando è disponibile nella BuildTool cartella dell'eliminazione dell'SDK. Esegue la stessa funzione delle destinazioni plug-in/.NET di Gradle descritte in precedenza, ma può essere integrata nei sistemi di compilazione personalizzati. Poiché è più generico, è più complesso da richiamare, quindi le destinazioni plug-in/.NET di Gradle devono essere usate quando possibile.

Uso dello strumento Command-Line

Lo strumento da riga di comando può essere richiamato usando gli script helper forniti nella BuildTool\bin directory.

Lo strumento prevede i parametri seguenti.

L'opzione facoltativa --processed viene usata per abilitare le compilazioni incrementali. Il set di file/directory elencati qui deve essere disgiunto con gli elenchi di input e classpath.

Chiamata dello strumento Command-Line di esempio

> BuildTool\bin\BuildTool.bat --input build\product-foo-project;libs\bar.jar --output mam-build\product-foo-project;mam-build\libs\bar.jar --classpath build\zap.jar;libs\Microsoft.Intune.MAM.SDK\classes.jar;%ANDROID_SDK_ROOT%\platforms\android-27\android.jar --excludeClasses com.contoso.SplashActivity

Ciò avrebbe gli effetti seguenti:

• la product-foo-project directory viene riscritta in mam-build\product-foo-project
• bar.jar viene riscritto in mam-build\libs\bar.jar
• zap.jar non viene riscritto perché è elencato solo in--classpath
• La com.contoso.SplashActivity classe non viene riscritta anche se è in --input

Impostazione di MAMApplication

Se l'app crea una sottoclasse di , lo strumento da riga di android.app.Applicationcomando/plug-in di compilazione trasformerà la classe dell'applicazione.

Se l'app non esegue la sottoclasse android.app.Application, è necessario impostare "com.microsoft.intune.mam.client.app.MAMApplication" come "android:name" attributo nel tag del <application> AndroidManifest.xml.

Procedure consigliate per Android

• Usare gli strumenti di compilazione più recenti di Android SDK.
• Rimuovere tutte le librerie non necessarie e inutilizzate, ad esempio android.support.v4.

Dopo aver eseguito sostituzioni automatiche, Intune App SDK mantiene comunque il contratto fornito dall'API Android. Tuttavia, le condizioni di errore possono essere attivate più frequentemente a causa dell'applicazione dei criteri. Queste procedure consigliate per Android ridurranno la probabilità di errore:

• Le funzioni di Android SDK che possono essere restituite null hanno ora una maggiore probabilità di restituire null. Assicurarsi che null i controlli proteggano queste chiamate di funzione.
• Le funzionalità che è possibile verificare, ad clipboardManager.getPrimaryClipDescription()esempio , devono essere controllate tramite le API di sostituzione MAM, ad MAMClipboard.getPrimaryClipDescription(clipboardManager)esempio .
• Tutte le funzioni derivate devono chiamare le versioni delle classi super.
• Evitare l'uso di qualsiasi API in modo ambiguo. Ad esempio, l'uso di Activity.startActivityForResult senza controllare l'oggetto requestCode causerà un comportamento strano.

Servizi

L'imposizione dei criteri può influire sulle interazioni del servizio Android. I metodi che stabiliscono una connessione al servizio associato, ad Context.bindService esempio, potrebbero non riuscire a causa dell'applicazione dei criteri sottostanti in Service.onBind e possono causare ServiceConnection.onNullBinding o ServiceConnection.onServiceDisconnected. L'interazione con un servizio associato stabilito può generare un'eccezione SecurityException a causa dell'applicazione dei criteri in Binder.onTransact.

I client dei servizi associati sono fortemente invitati a verificare la presenza di eccezioni generate dal servizio anziché consentire la propagazione delle eccezioni al resto dell'applicazione client.

Criteri di uscita

Dopo aver configurato il plug-in di compilazione o aver integrato lo strumento da riga di comando nel processo di compilazione, verificare che sia in esecuzione correttamente:

• Assicurarsi che la compilazione venga compilata e compilata correttamente.
• Configurare il report flag, quindi aprire il documento del report e verificare che si verifichino sostituzioni di classi e metodi:
  • Se si usa il plug-in, seguire la procedura descritta in Creazione di report.
  • Se si usa lo strumento da riga di comando, includere il --report flag .
• Se si usa il plug-in, configurare il verify flag e assicurarsi che non generi errori. Vedere Verifica.
• Controllare tutte le esclusioni (excludeProjects, excludeClassese excludeVariants) in build.gradle. Verificare che ogni esclusione sia necessaria e che non si occupi dei dati protetti. In passato si sono verificati molti errori di perdita di dati a causa di esclusioni troppo aggressive.
• Senza il portale aziendale di Intune installato, avviare l'app compilata, accedere con un utente di Microsoft Entra non destinato ai criteri di protezione delle app e verificare che l'app funzioni come previsto.
  • Disconnettersi e ripetere questo test con il portale aziendale di Intune installato.

Domande frequenti

L'app in precedenza integrava l'SDK senza il plug-in di compilazione; come è possibile usare il plug-in di compilazione?

Le versioni precedenti di Intune App SDK non includevano alcun modo automatizzato per eseguire sostituzioni di classi e metodi e gli sviluppatori dovevano eseguire queste sostituzioni manualmente nel codice sorgente. Se l'app in precedenza si era integrata in questo modo, è sicuro applicare il plug-in di compilazione (o lo strumento di compilazione da riga di comando) senza alcuna modifica del codice sorgente. Il progetto deve comunque elencare MAM SDK come dipendenza.

Operazioni successive

Dopo aver completato tutti i criteri di uscita, passare alla fase 4: MAM Integration Essentials.