Intune App SDK für Android – Erste Schritte mit MAM

Mit dem Microsoft Intune App SDK für Android können Sie Intune App-Schutzrichtlinien in Ihre native Java/Kotlin Android-App integrieren. Diese Richtlinien werden auch als MAM-Richtlinien bezeichnet. Eine Intune verwaltete Anwendung ist eine Anwendung, die in das Intune App SDK integriert ist. Wenn Intune die App aktiv verwaltet, können Intune Administratoren problemlos App-Schutzrichtlinien für Ihre Intune verwaltete App bereitstellen.

Phase 3: Erste Schritte mit MAM

Etappenziele

• Laden Sie das Intune App SDK herunter.
• Erfahren Sie, welche Dateien im Intune App SDK enthalten sind.
• Verweisen Sie in Ihrer Anwendung auf das Intune App SDK.
• Konfigurieren Sie das Intune App Gradle Build-Plug-In, oder verwenden Sie das Befehlszeilenbuildtool.
• Vergewissern Sie sich, dass das Intune App SDK ordnungsgemäß in Ihrem Build enthalten ist.

Hintergrund

Nachdem Ihre Anwendung MSAL erfolgreich integriert hat, ist es an der Zeit, das Intune App SDK herunterzuladen und in den Buildprozess Ihrer Anwendung einzubeziehen.

Ein großer Teil der Integration des Intune App SDK besteht darin, Android-Standardklassen und Methodenaufrufe durch Intune Versionen dieser Klassen und Methodenaufrufe zu ersetzen. Das SDK enthält Buildtools, mit denen die meisten dieser Ersetzungen automatisch für Sie erstellt werden. Weitere Informationen zu dieser Ersetzungslogik finden Sie im Abschnitt Ersetzungen von Klassen und Methoden im Anhang.

Herunterladen des Intune App SDK

Informationen zum Herunterladen des SDK finden Sie unter Herunterladen der SDK-Dateien.

Was ist im SDK enthalten?

Das Intune App SDK besteht aus den folgenden Dateien:

• Microsoft. Intune. MAM. SDK.aar: Die SDK-Komponenten, mit Ausnahme der JAR-Dateien der Supportbibliothek.
• com.microsoft.intune.mam.build.jar: Ein Gradle-Plug-In, das die Integration des SDK unterstützt.
• CHANGELOG.md: Stellt einen Datensatz der Änderungen bereit, die in jeder SDK-Version vorgenommen wurden.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: Dieses Android Archiv (AAR) enthält Stubs für Android-Systemklassen, die nur auf neueren Geräten vorhanden sind, aber von Methoden in MAMActivity referenziert werden. Neuere Geräte ignorieren diese Stubklassen. Diese AAR ist nur erforderlich, wenn Ihre App reflexionsbasierte Klassen ausführt, die von MAMActivityabgeleitet werden, und die meisten Apps müssen sie nicht einschließen. Der AAR enthält ProGuard-Regeln, um alle zugehörigen Klassen auszuschließen.

Verweisen auf Intune App-Bibliotheken

Das Intune App SDK ist eine Android-Standardbibliothek ohne externe Abhängigkeiten. Microsoft. Intune. MAM. SDK.aar enthält die Schnittstellen, die zum Aktivieren von App-Schutzrichtlinien erforderlich sind. Außerdem enthält sie den Code, der für die Interaktion mit der Microsoft Intune Unternehmensportal-App erforderlich ist.

Android Studio

Microsoft. Intune. MAM. SDK.aar muss als Android-Bibliotheksverweis angegeben werden. Informationen zum Hinzufügen dieser Abhängigkeit zu Ihrem Build finden Sie unter Hinzufügen Ihrer AAR- oder JAR-Datei als Abhängigkeit aus der Android-Dokumentation.

Visual Studio

Das NuGet-Paket Intune App SDK für .NET MAUI – Android muss als Abhängigkeit hinzugefügt werden.

Befolgen Sie den Vorgang zum Installieren und Verwalten von Paketen in Visual Studio mithilfe des NuGet-Paket-Managers.

Microsoft.Intune. MAM. SDK.aar ist gebunden, C#-Verweise zu erstellen, die auf den Microsoft.Intune.Mam Namespace begrenzt sind.

ProGuard

Ihre Anwendung verwendet möglicherweise bereits ProGuard (oder einen anderen Verkleinerungs-/Verschleierungsmechanismus) als Buildschritt. Das Intune App SDK verfügt über ProGuard-Konfigurationsregeln, die in diesem Buildschritt enthalten sein müssen. Einschließlich von . AAR in Ihrem Build integriert, wie zuvor beschrieben, die Konfiguration des SDK automatisch in den ProGuard-Schritt, sodass die erforderlichen Klassendateien beibehalten werden. Wenn Sie eingeschlossen haben . AAR, es ist keine andere Änderung erforderlich.

Die Microsoft Authentication Library (MSAL) wird mit einer eigenen ProGuard-Konfiguration ausgeliefert. Wenn Ihre App MSAL integriert, finden Sie weitere Informationen in der MSAL-Dokumentation .

Buildtools

Das SDK bietet Buildtools (ein Plug-In für Gradle-Builds, Ziele für .NET-Builds und ein Befehlszeilentool), die MAM-Ersetzungen automatisch ausführen. Diese Tools transformieren die von der Java-Kompilierung generierten Klassendateien. sie ändern nicht den ursprünglichen Quellcode. Sie müssen entweder das Gradle-Plug-In, das .NET-NuGet-Paket oder das Befehlszeilentool verwenden.

Die Buildtools allein reichen nicht aus, um Ihre Anwendung vollständig zu integrieren. Die Tools führen nur Klassen- und Methodenersetzungen durch . Sie führen keine komplexeren SDK-Integrationen wie Multi-Identity, Registrieren für App-Schutzrichtlinie, Richtlinie zum Einschränken der Datenübertragung zwischen Apps und Geräten oder Cloudspeicherorten oderMSAL-Konfiguration durch. Sie müssen diese Integrationen abschließen, bevor Ihre App vollständig Intune aktiviert ist. Lesen Sie den Rest dieser Dokumentation sorgfältig auf Integrationspunkte, die für Ihre App relevant sind.

Debugging

Die Buildtools führen nach der Kompilierung Ersetzungen durch. Diese Ersetzungen ändern einige Methodennamen. Daher kann das Debuggen von Haltepunkten, die für Methodennamen festgelegt wurden, beeinträchtigt werden. Sie werden möglicherweise nicht wie erwartet angehalten. Zeilennummernhaltepunkte sind nicht betroffen.

MAM im Stapel

Die integration Intune App SDK basiert stark auf Klassen- und Methodenersetzungen. Aufgrund dieser Abhängigkeit sehen mam Sie in Ihren Stapelablaufverfolgungen. Wenn Ihre App nicht über ein Konto verfügt, für das App-Schutzrichtlinien gelten, ist dieser gesamte MAM-Code inaktiv. Funktioniert z. B MAMActivity . identisch mit Activity und onMAMCreate funktioniert identisch mit onCreate. Wenn in einem Stapel angezeigt mam wird, überprüfen Sie zunächst Folgendes:

• Ist das Konto mit App-Schutzrichtlinien ausgerichtet?
• Ist die Intune-Unternehmensportal installiert?

Sofern die Antwort auf beide nicht "Ja" lautet, fungiert der MAM-Code als einfaches Passthrough.

Welches Tool benötige ich?

Wenn Sie Ihre App mit Gradle erstellen, lesen Sie Integrieren in das Gradle-Build-Plug-In.

Wenn Sie Ihre App mit .NET MAUI erstellen, lesen Sie Integrieren in die .NET MAUI-Ziele.

Wenn Sie Ihre App mit keinem der vorherigen Tools erstellen, lesen Sie Integrieren in das Befehlszeilentool.

Integration in das Gradle Build-Plug-In

Das Intune App SDK-Plug-In wird als Teil des SDK als GradlePlugin/com.microsoft.intune.mam.build.jar verteilt.

Damit das Plug-In von Gradle erkannt wird, muss es dem buildscript Klassenpfad hinzugefügt werden. Das Plug-In hängt von Javassist ab, das ebenfalls hinzugefügt werden muss. Weitere Informationen zur Javassist-Abhängigkeit finden Sie unter Abhängigkeiten.

Um diese dem Klassenpfad hinzuzufügen, fügen Sie Folgendes zu Ihrem Stamm hinzu 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")
    }
}

Um das Plug-In anzuwenden, fügen Sie der build.gradle Datei für Ihre App und dynamische Featuremodule Folgendes hinzu:

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

Standardmäßig arbeitet das Plug-In mit project Abhängigkeiten und externen Bibliotheken. Die Testkompilierung ist nicht betroffen.

Abhängigkeiten

Das Gradle-Plug-In verfügt über eine Abhängigkeit von Javassist, die für die Abhängigkeitsauflösung von Gradle verfügbar gemacht werden muss. Javassist wird ausschließlich zur Buildzeit verwendet, wenn das Plug-In ausgeführt wird, und Ihrer App wird kein Javassist-Code hinzugefügt.

Kompatibilitätsmatrix

Das MAM SDK-Build-Plug-In entspricht den Android-Buildanforderungen und Kompatibilitätstabellen. Versionen, die hier nicht aufgeführt sind, funktionieren möglicherweise oder nicht.

Ausschlüsse

Es können weitere Konfigurationen bereitgestellt werden, um bestimmte Komponenten in Ihrer App von Neuschreibungen auszuschließen. Ausschlüsse sind in erster Linie für Komponenten nützlich, die für MAM nicht relevant sind (d. a. keine Unternehmensdaten verarbeiten oder anzeigen).

Ausschlüsse können für unterschiedliche Bereiche konfiguriert werden:

• excludeProjects ermöglicht das Ausschließen einer Liste von Gradle-Projekten. Diese Ausschlüsse sind nützlich für Projekte, die keine Schnittstellen zu Android-Bibliotheken oder System-APIs haben. Sie sind auch nützlich für Projekte, die keine Unternehmensdaten verarbeiten. Beispielsweise kann ein Projekt, das ausschließlich nativen Code zum Ausführen von Netzwerkvorgängen auf niedriger Ebene enthält, ein guter Kandidat sein. Wenn ein Projekt im Großen und Ganzen mit Android-Bibliotheken oder System-APIs zusammenarbeitet, vermeiden Sie diese Ausschlüsse.
• excludeClasses ermöglicht das Ausschließen einer Liste von Klassen. Diese Ausschlüsse sind nützlich für Klassen, die keine Unternehmensdaten verarbeiten oder präsentieren. Beispielsweise sind Begrüßungsbildschirme und Onboardings Activitygute Kandidaten. Eine Klasse kann nicht ausgeschlossen werden, wenn eine ihrer Superklassen verarbeitet wird.
• excludeVariants ermöglicht das Ausschließen von Projektvarianten. Diese Ausschlüsse können sich entweder auf einen vollständigen Variantennamen oder eine einzelne Variante beziehen. Sie sind besonders nützlich, wenn Sie eine Nicht-MAM-Variante Ihrer App erstellen möchten. Wenn Ihre App beispielsweise über Buildtypen debug und release mit den Varianten {noMAM, MAM} und {mock, } verfügt, productionkönnen Sie Folgendes angeben:
  • noMAM , um alle Varianten mit der Variante noMAM auszuschließen, oder
  • noMAMMockDebug , um nur diese genaue Variante auszuschließen.

Beispiel für partielle build.gradle mit Ausschlüssen

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']
}

Dies hätte folgende Auswirkungen:

• :product:FooLib wird nicht neu geschrieben, da es in enthalten ist excludeProjects
• :product:foo-project wird umgeschrieben, mit Ausnahme com.contoso.SplashActivityvon , das übersprungen wird, da es sich in befindet excludeClasses
• com.microsoft.bar:baz.1.0.0 wird neu geschrieben, da alle externen Bibliotheken zur Verarbeitung eingeschlossen werden.
• Varianten mit der noMAM Variante werden nicht neu geschrieben.

Reporting

Das Build-Plug-In kann einen HTML-Bericht der vorgenommenen Änderungen generieren. Um die Generierung dieses Berichts anzufordern, geben Sie im intunemam Konfigurationsblock anreport = true. Wenn er generiert wird, wird der Bericht im Buildverzeichnis geschrieben outputs/logs .

intunemam {
    report = true
}

Verifizierung

Das Build-Plug-In kann weitere Überprüfungen ausführen, um nach möglichen Fehlern in Verarbeitungsklassen zu suchen. Diese Überprüfungen helfen beim Schutz vor potenziellen durch Plug-Ins verursachten Laufzeitfehlern.

Um die Überprüfung in Ihrem Build anzufordern, geben Sie im intunemam Konfigurationsblock anverify = true. Dies kann der Zeit, die von der Aufgabe des Plug-Ins benötigt wird, mehrere Sekunden hinzufügen.

intunemam {
    verify = true
}

Im Allgemeinen stellt ein Überprüfungsfehler einen Fehler im Build-Plug-In dar. Um Hilfe bei einem Fehler zu erhalten, eskalieren Sie das Problem mit dem Microsoft-Support. Wenn Sie keinen Microsoft-Supportvertrag haben, öffnen Sie ein GitHub-Problem.

Inkrementelle Builds

Um die Unterstützung für inkrementelles Erstellen zu aktivieren, geben Sie im intunemam Konfigurationsblock anincremental = true. Dieses Feature erhöht die Buildleistung, indem nur die Eingabedateien verarbeitet werden, die sich ändern. Die Standardkonfiguration für incremental ist false.

intunemam {
    incremental = true
}

Konfiguration des dynamischen Featuremoduls

Dynamische Featuremodule werden getrennt vom App-Projekt erstellt. Daher müssen dynamische Featuremodule auch das Gradle-Build-Plug-In anwenden.

Das Gradle-Plug-In weist technische Einschränkungen in den apIs auf, die es verwendet. Aufgrund dieser Einschränkungen müssen App-Klassen beim Transformieren dynamischer Featuremodulklassen erneut verarbeitet werden. Um sicherzustellen, dass diese erneute Verarbeitung durchgeführt werden kann, konfigurieren Sie alle Featuremodule mit den gleichen Einstellungen wie die App.

Wenn eine App beispielsweise eine Klasse ausschließt, sollte das dynamische Featuremodul auch diese Klasse ausschließen.

Integration in die .NET MAUI-Ziele

Die Intune App SDK-Ziele werden als Teil des SDK als Microsoft.Intune verteilt. Maui.Essentials.android.targets.

Die Ziele werden automatisch zur Kompilierzeit in Ihre Anwendung importiert, sobald das NuGet-Paket Intune App SDK für .NET MAUI – Android hinzugefügt wurde.

Integration in das Befehlszeilen-Buildtool

Das Befehlszeilenbuildtool ist im BuildTool Ordner des SDK-Drops verfügbar. Sie führt die gleiche Funktion wie das Gradle-Plug-In und die oben beschriebenen .NET-Ziele aus. Das Befehlszeilentool kann jedoch in benutzerdefinierte Buildsysteme integriert werden. Da das Tool generischer ist, ist es komplexer, es aufzurufen. Verwenden Sie nach Möglichkeit das Gradle-Plug-In oder .NET-Ziele.

Verwenden des Command-Line Tools

Das Befehlszeilentool kann mithilfe der bereitgestellten Hilfsskripts im BuildTool\bin Verzeichnis aufgerufen werden.

Das Tool erwartet die folgenden Parameter.

Die optionale --processed Option wird verwendet, um inkrementelle Builds zu aktivieren. Die hier aufgeführten Dateien/Verzeichnisse sollten mit den Eingabe- und Klassenpfadlisten getrennt sein.

Beispiel für Command-Line Toolaufruf

> 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

Dies hätte folgende Auswirkungen:

• Das product-foo-project Verzeichnis wird in umgeschrieben. mam-build\product-foo-project
• bar.jar wird in umgeschrieben. mam-build\libs\bar.jar
• zap.jar wird nicht neu geschrieben, da es nur in aufgeführt ist --classpath
• Die com.contoso.SplashActivity -Klasse wird nicht neu geschrieben, auch wenn sie sich in befindet --input

Festlegen von MAMApplication

Wenn Ihre App eine Unterklasse von android.app.Applicationerstellt, transformiert das Build-Plug-In oder das Befehlszeilentool Ihre Anwendungsklasse.

Wenn Ihre App keine Unterklasse android.app.Applicationaufweist, müssen Sie als "android:name" Attribut im Tag Ihres AndroidManifest.xml <application> festlegen"com.microsoft.intune.mam.client.app.MAMApplication".

Empfohlene bewährte Methoden für Android

• Verwenden Sie die neuesten Android SDK-Buildtools.
• Entfernen Sie alle unnötigen und nicht verwendeten Bibliotheken (z. B. android.support.v4).

Nach dem Ausführen automatischer Ersetzungen behält das Intune App SDK weiterhin den von der Android-API bereitgestellten Vertrag bei. Fehlerbedingungen können jedoch aufgrund der Richtlinienerzwingung häufiger ausgelöst werden. Diese bewährten Android-Methoden verringern die Wahrscheinlichkeit eines Fehlers:

• Android SDK-Funktionen, die zurückgeben null können, haben jetzt eine höhere Wahrscheinlichkeit, dass zurückgegeben wird null. Stellen Sie sicher, dass null überprüfungen diese Funktionsaufrufe schützen.
• Features, die überprüft werden können, z clipboardManager.getPrimaryClipDescription(). B. , müssen über ihre MAM-Ersetzungs-APIs wie MAMClipboard.getPrimaryClipDescription(clipboardManager)überprüft werden.
• Alle abgeleiteten Funktionen müssen ihre Superklassenversionen aufrufen.
• Vermeiden Sie die Verwendung einer API auf mehrdeutige Weise. Beispielsweise führt die Verwendung ohne Activity.startActivityForResult Überprüfung der zu requestCode einem seltsamen Verhalten.

Dienste

Die Richtlinienerzwingung kann sich auf Android-Dienstinteraktionen auswirken. Methoden, die eine gebundene Dienstverbindung wie Context.bindService herstellen, können aufgrund der zugrunde liegenden Richtlinienerzwingung in Service.onBind fehlschlagen und zu oder ServiceConnection.onServiceDisconnectedführenServiceConnection.onNullBinding. Die Interaktion mit einem eingerichteten gebundenen Dienst kann aufgrund der Richtlinienerzwingung in Binder.onTransactauslösenSecurityException.

Clients gebundener Dienste werden empfohlen, nach Ausnahmen zu suchen, die vom Dienst ausgelöst werden. Ausnahmen werden nicht an den Rest der Clientanwendung weitergegeben.

Exitkriterien

Nachdem Sie entweder das Build-Plug-In konfiguriert oder das Befehlszeilentool in Ihren Buildprozess integriert haben, überprüfen Sie, ob es erfolgreich ausgeführt wird:

• Stellen Sie sicher, dass Ihr Build erfolgreich kompiliert und erstellt wird.
• Konfigurieren Sie das report Flag, öffnen Sie dann das Berichtsdokument, und vergewissern Sie sich, dass Klassen- und Methodenersetzungen vorgenommen werden:
  • Wenn Sie das Plug-In verwenden, führen Sie die Schritte unter Berichterstellung aus.
  • Wenn Sie das Befehlszeilentool verwenden, fügen Sie das Flag ein --report .
• Wenn Sie das Plug-In verwenden, konfigurieren Sie das verify Flag, und stellen Sie sicher, dass es keine Fehler erzeugt. Weitere Informationen finden Sie unter Überprüfung.
• Überprüfen Sie alle Ausschlüsse (excludeProjects, excludeClassesund excludeVariants) in build.gradle. Vergewissern Sie sich, dass jeder Ausschluss erforderlich ist und nicht mit geschützten Daten zu tun hat. In der Vergangenheit sind viele Datenleckfehler aufgrund von zu aggressiven Ausschlüssen aufgetreten.
• Starten Sie ihre kompilierte App, ohne dass die Intune-Unternehmensportal installiert ist. Melden Sie sich mit einem Microsoft Entra Benutzer an, für den keine App-Schutzrichtlinie gilt. Vergewissern Sie sich, dass die App wie erwartet funktioniert.
  • Melden Sie sich ab, und wiederholen Sie diesen Test mit installiertem Intune-Unternehmensportal.

Häufig gestellte Fragen

Meine App hat das SDK zuvor ohne das Build-Plug-In integriert. wie kann ich das Build-Plug-In verwenden?

Ältere Versionen des Intune App SDK boten keine automatisierte Möglichkeit, Klassen- und Methodenersetzungen durchzuführen. Entwickler mussten diese Ersetzungen manuell im Quellcode ausführen. Wenn Ihre App auf diese Weise integriert ist, ist es sicher, das Build-Plug-In oder das Befehlszeilen-Buildtool anzuwenden. Sie benötigen keine Änderungen am Quellcode. Ihr Projekt muss das MAM SDK weiterhin als Abhängigkeit auflisten.

Nächste Schritte

Nachdem Sie alle Exitkriterien erfüllt haben, fahren Sie mit Phase 4: MAM Integration Essentials fort.