Intune App SDK per Android - Introduzione a MAM

L'SDK dell'app Microsoft Intune per Android consente di incorporare i criteri di protezione dell'app Intune nell'app Android Java/Kotlin nativa. Questi criteri sono noti anche come criteri MAM. Un'applicazione gestita da Intune è un'applicazione integrata con l'SDK per app di Intune. Quando Intune gestisce attivamente l'app, gli amministratori di Intune possono distribuire facilmente i criteri di protezione delle app all'app gestita da Intune.

Fase 3: Introduzione a MAM

Obiettivi della fase

• Scaricare l'SDK dell'app Intune.
• Informazioni sui file inclusi in Intune App SDK.
• Fare riferimento a Intune App SDK nell'applicazione.
• Configura il plug-in di compilazione Gradle dell'app Intune o usa 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 consiste nel sostituire le classi Android standard e le chiamate ai metodi con le versioni di Intune di tali classi e chiamate ai metodi. L'SDK include strumenti di compilazione che eseguono 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, consulta Scaricare i file SDK.

Cosa c'è nell'SDK?

Intune App SDK è costituito dai file seguenti:

• Microsoft. Intune. MAM. SDK.aar: i componenti SDK, ad eccezione dei file JAR della libreria di supporto.
• com.microsoft.intune.mam.build.jar: un plug-in Gradle, che aiuta a integrare l'SDK.
• CHANGELOG.md: Fornisce un record delle modifiche apportate in ogni versione dell'SDK.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: questo archivio Android (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 la reflection sulle classi derivanti da MAMActivity, e la maggior parte delle app non deve includerlo. L'AAR contiene regole ProGuard per escludere tutte le sue classi.

Riferimenti alle librerie di app di Intune

Intune App SDK è una libreria Android standard senza dipendenze esterne. Microsoft. Intune. MAM. SDK.aar contiene le interfacce necessarie per abilitare i criteri di protezione delle app. Contiene inoltre 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. Per aggiungere questa dipendenza alla build, segui Aggiungere il tuo AAR o JAR come dipendenza dalla documentazione di Android.

Visual Studio

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

Seguire la procedura per Installare e gestire i pacchetti in Visual Studio usando Gestione pacchetti NuGet.

Microsoft.Intune. MAM. SDK.aar è associato alla creazione di riferimenti C# nell'ambito dello Microsoft.Intune.Mam spazio dei nomi.

ProGuard

È possibile che l'applicazione usi già ProGuard (o qualsiasi altro meccanismo di compattazione/offuscamento) come passaggio di compilazione. L'SDK dell'app Intune dispone di regole di configurazione ProGuard che devono essere incluse in tale passaggio di compilazione. Incluso il . 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 il valore . AAR, non sono necessarie altre modifiche.

La libreria di autenticazione Microsoft (MSAL) viene fornita con la propria configurazione ProGuard. Se l'app integra MSAL, vedere la documentazione di MSAL per altri dettagli.

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 le 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 nel cloud o la configurazione MSAL. È necessario completare queste integrazioni prima che l'app sia completamente abilitata per Intune. Esamina attentamente il resto di questa documentazione per trovare punti di integrazione rilevanti per la tua app.

Debug

Gli strumenti di compilazione eseguono le sostituzioni dopo la compilazione. Queste sostituzioni modificano alcuni nomi di metodi. Di conseguenza, i punti di interruzione di debug impostati sui nomi dei metodi potrebbero essere interessati. Potrebbero non fermarsi come previsto. I punti di interruzione del numero di riga non sono interessati.

MAM nello stack

L'integrazione di Intune App SDK si basa principalmente sulle sostituzioni di classi e metodi. A causa di questa dipendenza, vedi mam in tutte le tracce dello stack. Quando l'app non ha un account destinato con criteri di protezione delle app, tutto questo codice MAM rimane dormiente. Ad esempio, MAMActivity funziona in modo identico e funziona in modo identico a onMAMCreateActivityonCreate. Ogni volta che vedi mam in una pila, controlla prima di tutto:

• L'account è oggetto di criteri di protezione delle app?
• Il Portale aziendale Intune è installato?

A meno che la risposta a entrambi non sia "sì", il codice MAM funge da semplice passthrough.

Di quale strumento ho bisogno?

Se crei la tua app con Gradle, consulta Integrazione con il plug-in di compilazione Gradle

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

Se si compila l'app con nessuno degli strumenti 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 plugin venga riconosciuto da Gradle, deve essere aggiunto al buildscript classpath. Il plugin dipende da Javassist, che deve essere anch'esso aggiunto. Per ulteriori informazioni sulla dipendenza di Javassist, consulta Dipendenze.

Per aggiungerli al percorso di classe, aggiungi 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 e i build.gradle moduli delle funzionalità dinamiche:

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

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

Dipendenze

Il plugin Gradle ha una dipendenza da Javassist, che deve essere resa disponibile per la risoluzione delle dipendenze di Gradle. Javassist viene utilizzato esclusivamente in fase di compilazione durante l'esecuzione del plug-in e nessun codice Javassist viene aggiunto all'app.

Matrice di compatibilità

Il plug-in di compilazione dell'SDK MAM è allineato ai requisiti di compilazione e alle tabelle di compatibilità di Android. Le versioni non elencate qui potrebbero funzionare o meno.

Esclusioni

È possibile fornire altre configurazioni per escludere componenti specifici dell'app dalle riscritture. Le esclusioni sono utili soprattutto per i componenti che non sono rilevanti per MAM, ovvero che non gestiscono o visualizzano i dati aziendali.

Le esclusioni possono essere configurate per vari ambiti:

• 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. Sono utili anche per i progetti che 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 librerie Android o API di sistema, evitare queste esclusioni.
• excludeClasses Consente di escludere un elenco di classi. Queste esclusioni sono utili per le classi che non gestiscono o non presentano dati aziendali. Ad esempio, le schermate iniziali e le schermate di onboarding Activitysono buoni candidati. Una classe non può essere esclusa se una qualsiasi delle sue superclassi viene elaborata.
• excludeVariants Consente di escludere le varianti del progetto. Queste esclusioni possono riferirsi a un nome di variante completo o a una singola versione. Sono particolarmente utili se vuoi creare una versione non MAM della tua app. Ad esempio, se l'app ha tipi di debug build e release con caratteristiche {noMAM, MAM} e {mock, production}, puoi specificare:
  • noMAM per escludere tutte le varianti con gusto noMAM o
  • noMAMMockDebug per escludere solo quella 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 i seguenti effetti:

• :product:FooLib non viene riscritto perché è incluso in excludeProjects
• :product:foo-project è riscritto, tranne , com.contoso.SplashActivityche viene saltato 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 rapporto html delle modifiche apportate. Per richiedere la generazione di questo report, specificare report = true nel blocco di intunemam configurazione. Se generato, il rapporto viene scritto outputs/logs nella directory di compilazione.

intunemam {
    report = true
}

Verifica

Il plug-in di compilazione può eseguire più verifiche per cercare possibili errori nelle classi di elaborazione. Questi controlli consentono di proteggersi da potenziali errori di runtime indotti dal plug-in.

Per richiedere che la verifica venga eseguita nella build, specificare verify = true nel blocco di intunemam configurazione. Questo potrebbe aggiungere diversi 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, inoltra il problema al supporto tecnico Microsoft. Se non hai un contratto di supporto Microsoft, apri un problema su GitHub.

Build incrementali

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

intunemam {
    incremental = true
}

Configurazione del modulo dinamico delle funzionalità

I moduli di funzionalità dinamici vengono compilati separatamente dal progetto app. Pertanto, i moduli di funzionalità dinamiche devono anche applicare il plug-in di compilazione Gradle.

Il plug-in Gradle presenta limitazioni tecniche nelle API che utilizza. A causa di queste limitazioni, le classi di app devono essere rielaborate durante la trasformazione delle classi di moduli dinamici delle funzionalità dinamiche. Per assicurarsi che il ricondizionamento possa essere eseguito, configurare tutti i moduli delle funzionalità con le stesse impostazioni dell'app.

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

Integrazione con le destinazioni .NET MAUI

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

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

Integrazione con lo strumento di compilazione della riga di comando

Lo strumento di compilazione della riga di comando è disponibile nella cartella della versione di rilascio dell'SDK BuildTool . Svolge la stessa funzione del plug-in Gradle e dei target .NET descritti sopra. Tuttavia, lo strumento da riga di comando può essere integrato in sistemi di compilazione personalizzati. Poiché lo strumento è più generico, è più complesso da richiamare. Usa il plug-in Gradle o le destinazioni .NET quando possibile.

Uso dello strumento Command-Line

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

Lo strumento prevede i seguenti parametri.

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

Esempio di chiamata allo strumento Command-Line

> 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 i seguenti effetti:

• 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 , il plug-in di compilazione o lo strumento da riga di comando trasforma la classe dell'applicazione android.app.Application.

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

Procedure consigliate per Android

• Usa gli strumenti di compilazione Android SDK più recenti.
• Rimuovi tutte le raccolte non necessarie e inutilizzate (ad esempio, android.support.v4).

Dopo aver eseguito le sostituzioni automatiche, l'SDK per app Intune mantiene comunque il contratto fornito dall'API Android. Tuttavia, le condizioni di errore potrebbero essere attivate più frequentemente come risultato dell'applicazione dei criteri. Queste procedure consigliate di Android riducono la probabilità di errore:

• Le funzioni Android SDK che possono restituire null ora hanno una maggiore probabilità di restituire null. Assicurarsi che null i controlli proteggano queste chiamate di funzione.
• Le funzionalità che possono essere verificate, ad esempio clipboardManager.getPrimaryClipDescription(), devono essere verificate tramite le API sostitutive di MAM, ad esempio MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Tutte le funzioni derivate devono chiamare le loro versioni di superclasse.
• Evitare l'uso di qualsiasi API in modo ambiguo. Ad esempio, l'uso Activity.startActivityForResult senza controllare provoca un requestCode comportamento strano.

Servizi

L'applicazione dei criteri potrebbe influire sulle interazioni del servizio Android. Metodi che stabiliscono una connessione al servizio associato, ad esempio potrebbe Context.bindService non riuscire a causa dell'imposizione di criteri sottostanti in Service.onBind e potrebbe comportare ServiceConnection.onNullBinding o ServiceConnection.onServiceDisconnected. L'interazione con un servizio associato stabilito potrebbe generare un SecurityException errore dovuto all'imposizione dei criteri in Binder.onTransact.

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

Criteri di chiusura

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

• Assicurarsi che la compilazione venga compilata correttamente.
• Configurare il report contrassegno, quindi aprire il documento del report e verificare che si stiano verificando sostituzioni di classi e metodi:
  • Se usi il plug-in, segui i passaggi in Report.
  • Se si usa lo strumento da riga di comando, includere il --report contrassegno.
• Se si usa il plug-in, configurare il verify flag e assicurarsi che non generi errori. Vedere Verifica.
• Ricontrolla tutte le esclusioni (excludeProjects, excludeClasses, e excludeVariants) in build.gradle. Verificare che ogni esclusione sia necessaria e non riguardi i dati protetti. Storicamente, molti errori di perdita di dati si verificano a causa di esclusioni troppo aggressive.
• Senza il Portale aziendale Intune installato, avviare l'app compilata. Accedere con un utente di Microsoft Entra non interessato ai criteri di protezione delle app. Verifica che l'app funzioni come previsto.
  • Disconnettersi e ripetere il test con il Portale aziendale Intune installato.

Domande frequenti

La mia app in precedenza integrava l'SDK senza il plug-in di compilazione; come posso usare il plug-in di compilazione?

Le versioni precedenti di Intune App SDK non includevano alcun modo automatizzato per eseguire le sostituzioni di classi e metodi. Gli sviluppatori dovevano eseguire queste sostituzioni manualmente nel codice sorgente. Se l'app è integrata in questo modo, è sicuro applicare il plug-in di compilazione o lo strumento di compilazione da riga di comando. Non sono necessarie modifiche al codice sorgente. Il progetto deve comunque elencare MAM SDK come dipendenza.

Operazioni successive

Dopo aver completato tutti i criteri di uscita, continua con la fase 4: nozioni di base sull'integrazione MAM.