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.

Nota

Questa guida è suddivisa in diverse fasi distinte. Per iniziare, esaminare la fase 1: Pianificare l'integrazione.

Fase 3: Introduzione con MAM

Fase Goals

• 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 Microsoft Intune Portale aziendale.

Android Studio

Microsoft.Intune.MAM.SDK.aar deve essere specificato come riferimento alla libreria Android:

1. Aprire il progetto di app in Android Studio e passare al modulo Nuovo >> file.
2. Selezionare Importa. VASO/. Pacchetto AAR.
3. Selezionare Microsoft.Intune.MAM.SDK.aar per creare un modulo per . Tipo di file AAR .
4. Fare clic con il pulsante destro del mouse sul modulo o sui moduli contenenti il codice dell'app e passare allascheda>Dipendenze impostazioni> modulo+ icona>Dipendenza modulo.
5. Selezionare il modulo AAR di MAM SDK creato e selezionare OK. L'aggiunta di questo riferimento garantisce che il modulo venga compilato con MAM SDK quando si compila il progetto.

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 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 il build.gradle modulo dell'app:

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.

Nota

A partire da 8.0 Intune App SDK, non è più possibile elaborare le librerie in modo selettivo. Tutte le librerie vengono elaborate.

Dipendenze

Nota

È necessario usare la versione 3.6.1 o successiva del plug-in Android Gradle e la versione 5.6.4 o successiva di Gradle.

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.

Nota

Le versioni javassist potrebbero non essere compatibili con le versioni precedenti. In genere, è consigliabile usare la versione esatta prevista da Intune App SDK:

• Intune App SDK ≥ 10.0.0 richiede Javassist 3.29.2-GA
• Intune App SDK ≥ 7.0.0 richiede Javassist 3.27.0-GA
• Intune App SDK < 7.0.0 richiede Javassist 3.22.0-GA

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.

Attenzione

Le esclusioni non devono essere prese alla leggera. L'applicazione errata delle esclusioni può causare gravi perdite di dati nell'app. Convalidare sempre l'impatto di qualsiasi esclusione applicata.

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
}

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.

Parametro	Obbligatorio	Descrizione
--input	Sì	Elenco delimitato da punti e virgola di file jar e directory di file di classe da modificare. Devono essere incluse tutte le directory/jar che si intende riscrivere.
--output	Sì	Elenco delimitato da punti e virgola di file jar e directory in cui archiviare le classi modificate. Deve essere presente una voce di output per voce di input, che deve essere elencata in ordine.
--classpath	Sì	Classpath di compilazione. Questo può contenere sia le directory jar che le directory di classe.
--processed	No	Elenco delimitato da punti e virgola di file jar e directory contenenti classi già elaborate da una chiamata precedente dello strumento di compilazione.
--excludeClasses	No	Elenco delimitato da punti e virgola contenente i nomi delle classi che devono essere escluse dalla riscrittura.
--report	No	Directory in cui scrivere un report HTML sulle classi modificate. Se non specificato, non viene scritto alcun report.

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.

Consiglio

Nei sistemi unix-like punto e virgola è un separatore di comando. Per evitare che la shell divida i comandi, assicurarsi di eseguire l'escape di ogni punto e virgola con '' o di eseguire il wrapping del parametro completo tra virgolette.

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.jarnon viene riscritto perché è elencato solo in--classpath
• La com.contoso.SplashActivity classe non viene riscritta anche se è in --input

Avviso

Lo strumento di compilazione attualmente non supporta i file aar. Se il sistema di compilazione non estrae classes.jar già quando si gestiscono file aar, sarà necessario farlo prima di richiamare lo strumento di compilazione.

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 Intune installato, avviare l'app compilata, accedere con un utente Microsoft Entra non destinato ai criteri di protezione delle app e verificare che l'app funzioni come previsto.
  • Disconnettersi e ripetere il test con il Portale aziendale 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.