Intune App SDK voor Android - Aan de slag met MAM

Met de Microsoft Intune App SDK voor Android kunt u Intune beveiligingsbeleid voor apps opnemen in uw systeemeigen Java/Kotlin Android-app. Deze beleidsregels worden ook wel MAM-beleid genoemd. Een Intune beheerde toepassing is een toepassing die is geïntegreerd met de Intune App SDK. Wanneer Intune de app actief beheert, kunnen Intune beheerders eenvoudig app-beveiligingsbeleid implementeren in uw Intune beheerde app.

Fase 3: Aan de slag met MAM

Fasedoelen

• Download de Intune App SDK.
• Meer informatie over welke bestanden zijn opgenomen in de Intune App SDK.
• Raadpleeg de Intune App SDK in uw toepassing.
• Configureer de Intune App Gradle Build-invoegtoepassing of gebruik het buildhulpprogramma voor de opdrachtregel.
• Controleer of de Intune App SDK correct is opgenomen in uw build.

Achtergrond

Nu uw toepassing MSAL heeft geïntegreerd, is het tijd om de Intune App SDK te downloaden en op te nemen in het buildproces van uw toepassing.

Een groot deel van de integratie van de Intune App SDK is het vervangen van standaard Android-klassen en methode-aanroepen door Intune versies van deze klassen en methode-aanroepen. De SDK bevat build-hulpprogramma's waarmee de meeste van deze vervangingen automatisch voor u worden uitgevoerd. Als u meer wilt weten over deze vervangingslogica, raadpleegt u de sectie klasse- en methodevervangingen van de bijlage.

De Intune App SDK downloaden

Zie De SDK-bestanden downloaden om de SDK te downloaden.

Wat zit er in de SDK?

De Intune App SDK bestaat uit de volgende bestanden:

• Microsoft. Intune. MAM. SDK.aar: de SDK-onderdelen, met uitzondering van de JAR-bestanden van de ondersteuningsbibliotheek.
• com.microsoft.intune.mam.build.jar: een Gradle-invoegtoepassing, waarmee u de SDK kunt integreren.
• CHANGELOG.md: biedt een record van wijzigingen die zijn aangebracht in elke SDK-versie.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: dit Android Archief (AAR) bevat stubs voor Android-systeemklassen die alleen aanwezig zijn op nieuwere apparaten, maar waarnaar wordt verwezen door methoden in MAMActivity. Nieuwere apparaten negeren deze stub-klassen. Deze AAR is alleen nodig als uw app reflectie uitvoert op klassen die zijn afgeleid van MAMActivity, en de meeste apps hoeven deze niet op te nemen. De AAR bevat ProGuard-regels om alle bijbehorende klassen uit te sluiten.

Naar Intune app-bibliotheken verwijzen

De Intune App SDK is een standaard-Android-bibliotheek zonder externe afhankelijkheden. Microsoft. Intune. MAM. SDK.aar bevat de interfaces die nodig zijn voor het inschakelen van app-beveiligingsbeleid. Het bevat ook de code die nodig is om te werken met de Microsoft Intune Bedrijfsportal-app.

Android Studio

Microsoft. Intune. MAM. SDK.aar moet worden opgegeven als verwijzing naar een Android-bibliotheek. Als u deze afhankelijkheid wilt toevoegen aan uw build, volgt u Uw AAR of JAR toevoegen als een afhankelijkheid uit Android-documentatie.

Visual Studio

Het NuGet-pakket Intune App SDK voor .NET MAUI - Android moet als afhankelijkheid worden toegevoegd.

Volg het proces voor het installeren en beheren van pakketten in Visual Studio met behulp van NuGet Package Manager.

De Microsoft.Intune. MAM. SDK.aar is gebonden aan het maken van C#-verwijzingen die zijn gericht op de Microsoft.Intune.Mam naamruimte.

ProGuard

Uw toepassing maakt mogelijk al gebruik van ProGuard (of een ander mechanisme voor verkleinen/verduistering) als buildstap. De Intune App SDK bevat ProGuard-configuratieregels die moeten worden opgenomen in die buildstap. Inclusief de . AAR in uw build integreert, zoals eerder beschreven, automatisch de configuratie van de SDK in de ProGuard-stap, zodat de benodigde klassebestanden worden bewaard. Als u de hebt opgenomen. AAR, er is geen andere wijziging nodig.

De Microsoft Authentication Library (MSAL) wordt geleverd met een eigen ProGuard-configuratie. Als uw app MSAL integreert, raadpleegt u de MSAL-documentatie voor meer informatie.

Hulpprogramma's bouwen

De SDK biedt buildhulpprogramma's (een invoegtoepassing voor Gradle-builds, doelen voor .NET-builds en een opdrachtregelprogramma) waarmee MAM-vervangingen automatisch worden uitgevoerd. Deze hulpprogramma's transformeren de klassebestanden die worden gegenereerd door Java-compilatie; de oorspronkelijke broncode wordt niet gewijzigd. U moet de Gradle-invoegtoepassing, het .NET NuGet-pakket of het opdrachtregelprogramma gebruiken.

De buildhulpprogramma's alleen zijn niet voldoende om uw toepassing volledig te integreren. Met de hulpprogramma's worden alleen klasse- en methodevervangingen uitgevoerd. Ze voeren geen complexere SDK-integraties uit, zoals Multi-Identity, Registreren voor app-beveiligingsbeleid, Beleid voor het beperken van gegevensoverdracht tussen apps en apparaat- of cloudopslaglocaties of MSAL-configuratie. U moet deze integraties voltooien voordat uw app volledig is Intune ingeschakeld. Raadpleeg de rest van deze documentatie zorgvuldig voor integratiepunten die relevant zijn voor uw app.

Debugging

Het build-hulpprogramma voert vervangingen uit na compilatie. Met deze vervangingen worden enkele methodenamen gewijzigd. Als gevolg hiervan kunnen onderbrekingspunten voor foutopsporing die zijn ingesteld op methodenamen, worden beïnvloed. Ze stoppen mogelijk niet zoals verwacht. Onderbrekingspunten voor regelnummers worden niet beïnvloed.

MAM in de stack

De Intune App SDK-integratie is sterk afhankelijk van vervangingen van klassen en methoden. Vanwege deze afhankelijkheid ziet mam u in de hele stack traceringen. Wanneer uw app geen account heeft dat is gericht op app-beveiligingsbeleid, ligt al deze MAM-code inactief. Werkt bijvoorbeeld MAMActivity identiek aan Activity en onMAMCreate werkt identiek aan onCreate. Wanneer u in een stack ziet mam , controleert u eerst het volgende:

• Is het account gericht op app-beveiligingsbeleid?
• Is de Intune-bedrijfsportal geïnstalleerd?

Tenzij het antwoord op beide 'ja' is, fungeert de MAM-code als een eenvoudige passthrough.

Welk hulpprogramma heb ik nodig?

Als u uw app bouwt met Gradle, raadpleegt u Integreren met de Gradle Build-invoegtoepassing

Als u uw app bouwt met .NET MAUI, raadpleegt u Integreren met de .NET MAUI-doelen.

Als u uw app bouwt met geen van de vorige hulpprogramma's, raadpleegt u Integreren met het opdrachtregelprogramma.

Integreren met de Gradle Build-invoegtoepassing

De Intune App SDK-invoegtoepassing wordt als onderdeel van de SDK gedistribueerd als GradlePlugin/com.microsoft.intune.mam.build.jar.

Om ervoor te zorgen dat de invoegtoepassing wordt herkend door Gradle, moet deze worden toegevoegd aan het buildscript klassepad. De invoegtoepassing is afhankelijk van Javassist, die ook moet worden toegevoegd. Zie Afhankelijkheden voor meer informatie over de Javassist-afhankelijkheid.

Als u deze wilt toevoegen aan het klassepad, voegt u het volgende toe aan uw hoofdmap 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")
    }
}

Als u de invoegtoepassing wilt toepassen, voegt u vervolgens het volgende toe aan het build.gradle bestand voor uw app en dynamische functiemodules:

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

De invoegtoepassing werkt standaard op project afhankelijkheden en externe bibliotheken. Testcompilatie wordt niet beïnvloed.

Afhankelijkheden

De Gradle-invoegtoepassing heeft een afhankelijkheid van Javassist, die beschikbaar moet worden gesteld voor de afhankelijkheidsoplossing van Gradle. Javassist wordt alleen gebruikt tijdens het bouwen van de invoegtoepassing en er wordt geen Javassist-code toegevoegd aan uw app.

Compatibiliteitsmatrix

De MAM SDK Build-invoegtoepassing is afgestemd op de buildvereisten en compatibiliteitstabellen van Android. Versies die hier niet worden vermeld, werken mogelijk wel of niet.

Uitsluitingen

Er kunnen meer configuraties worden opgegeven om specifieke onderdelen in uw app uit te sluiten van herschrijfbewerkingen. Uitsluitingen zijn voornamelijk nuttig voor onderdelen die niet relevant zijn voor MAM (dat wil gezegd, bedrijfsgegevens niet verwerken of weergeven).

Uitsluitingen kunnen worden geconfigureerd voor verschillende bereiken:

• excludeProjects hiermee kunt u een lijst met Gradle-projecten uitsluiten. Deze uitsluitingen zijn handig voor projecten die geen interface hebben met Android-bibliotheken of systeem-API's. Ze zijn ook handig voor projecten die geen bedrijfsgegevens verwerken. Een project dat uitsluitend systeemeigen code bevat voor het uitvoeren van netwerkbewerkingen op laag niveau kan bijvoorbeeld een goede kandidaat zijn. Als een project in grote lijnen raakvlakken heeft met Android-bibliotheken of systeem-API's, vermijdt u deze uitsluitingen.
• excludeClasses staat het uitsluiten van een lijst met klassen toe. Deze uitsluitingen zijn handig voor klassen die geen bedrijfsgegevens verwerken of presenteren. Splash screens en onboarding Activitys zijn bijvoorbeeld goede kandidaten. Een klasse kan niet worden uitgesloten als een van de superklassen wordt verwerkt.
• excludeVariants schakelt het uitsluiten van projectvarianten in. Deze uitsluitingen kunnen verwijzen naar een volledige variantnaam of één smaak. Ze zijn vooral handig als u een niet-MAM-smaak van uw app wilt maken. Als uw app bijvoorbeeld buildtypen debug heeft en release de smaken {noMAM, MAM} en {mock, } bevat, productionkunt u het volgende opgeven:
  • noMAM om alle varianten met de smaak noMAM uit te sluiten of
  • noMAMMockDebug om alleen die exacte variant uit te sluiten.

Voorbeeld van gedeeltelijke build.gradle met uitsluitingen

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

Dit heeft de volgende gevolgen:

• :product:FooLib is niet herschreven omdat het is opgenomen in excludeProjects
• :product:foo-project is herschreven, met uitzondering com.contoso.SplashActivityvan , dat wordt overgeslagen omdat het is in excludeClasses
• com.microsoft.bar:baz.1.0.0 wordt herschreven omdat alle externe bibliotheken zijn opgenomen voor verwerking.
• Varianten met de noMAM smaak worden niet herschreven.

Rapportage

De build-invoegtoepassing kan een HTML-rapport genereren van de wijzigingen die worden aangebracht. Als u het genereren van dit rapport wilt aanvragen, geeft u op report = true in het intunemam configuratieblok. Als het rapport wordt gegenereerd, wordt het geschreven naar outputs/logs in de buildmap.

intunemam {
    report = true
}

Verificatie

De build-invoegtoepassing kan meer verificaties uitvoeren om te zoeken naar mogelijke fouten in verwerkingsklassen. Deze controles helpen bij het beveiligen tegen mogelijke runtimefouten die door invoegtoepassingen worden veroorzaakt.

Als u wilt dat verificatie wordt uitgevoerd in uw build, geeft u op verify = true in het intunemam configuratieblok. Dit kan enkele seconden toevoegen aan de tijd die nodig is voor de taak van de invoegtoepassing.

intunemam {
    verify = true
}

Over het algemeen vertegenwoordigt een verificatiefout een bug in de build-invoegtoepassing. Voor hulp bij een fout escaleert u het probleem met Microsoft-ondersteuning. Als u geen Microsoft-ondersteuningscontract hebt, opent u een GitHub-probleem.

Incrementele builds

Als u ondersteuning voor incrementeel bouwen wilt inschakelen, geeft u incremental = true op in het intunemam configuratieblok. Deze functie verhoogt de buildprestaties door alleen de invoerbestanden te verwerken die worden gewijzigd. De standaardconfiguratie voor incremental is false.

intunemam {
    incremental = true
}

Configuratie van module voor dynamische functies

Dynamische functiemodules worden afzonderlijk van het app-project gebouwd. Daarom moeten dynamische functiemodules ook de Gradle Build-invoegtoepassing toepassen.

De Gradle-invoegtoepassing heeft technische beperkingen in de API's die worden gebruikt. Vanwege deze beperkingen moeten app-klassen opnieuw worden verwerkt bij het transformeren van moduleklassen voor dynamische functies. Om ervoor te zorgen dat deze herverwerking kan worden uitgevoerd, configureert u alle functiemodules met dezelfde instellingen als de app.

Als een app bijvoorbeeld een klasse uitsluit, moet de module met dynamische functies die klasse ook uitsluiten.

Integreren met de .NET MAUI-doelen

De Intune App SDK-doelen worden als onderdeel van de SDK gedistribueerd als Microsoft.Intune. Maui.Essentials.android.targets.

De doelen worden automatisch geïmporteerd in uw toepassing tijdens het compileren zodra het NuGet-pakket Intune App SDK voor .NET MAUI - Android is toegevoegd.

Integreren met het buildhulpprogramma voor opdrachtregels

Het opdrachtregelprogramma voor build is beschikbaar in de BuildTool map van de SDK-drop. Het voert dezelfde functie uit als de Gradle-invoegtoepassing en .NET-doelen die hierboven worden beschreven. Het opdrachtregelprogramma kan echter worden geïntegreerd in aangepaste buildsystemen. Omdat het hulpprogramma algemener is, is het complexer om aan te roepen. Gebruik waar mogelijk de Gradle-invoegtoepassing of .NET-doelen.

Het hulpprogramma Command-Line gebruiken

Het opdrachtregelprogramma kan worden aangeroepen met behulp van de opgegeven helperscripts in de BuildTool\bin map.

Het hulpprogramma verwacht de volgende parameters.

De optionele --processed optie wordt gebruikt om incrementele builds in te schakelen. De set bestanden/mappen die hier worden vermeld, moet niet aan elkaar worden gekoppeld met de invoer- en classpath-lijsten.

Voorbeeld van aanroep van het hulpprogramma 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

Dit heeft de volgende gevolgen:

• de product-foo-project map wordt herschreven naar mam-build\product-foo-project
• bar.jar wordt herschreven naar mam-build\libs\bar.jar
• zap.jar is niet herschreven omdat deze alleen wordt vermeld in --classpath
• De com.contoso.SplashActivity klasse wordt niet herschreven, zelfs niet als deze in --input

MAMApplication instellen

Als uw app een subklasse van android.app.Applicationmaakt, transformeert de build-invoegtoepassing of het opdrachtregelprogramma uw toepassingsklasse.

Als uw app geen subklasse android.app.Applicationheeft, moet u instellen "com.microsoft.intune.mam.client.app.MAMApplication" als het kenmerk in de "android:name" tag van <application> uw AndroidManifest.xml.

Aanbevolen best practices voor Android

• Gebruik de nieuwste buildhulpprogramma's voor Android SDK.
• Verwijder alle overbodige en ongebruikte bibliotheken (bijvoorbeeld android.support.v4).

Na het uitvoeren van automatische vervangingen onderhoudt de Intune App SDK nog steeds het contract van de Android-API. Foutvoorwaarden kunnen echter vaker worden geactiveerd als gevolg van het afdwingen van beleid. Deze best practices voor Android verminderen de kans op fouten:

• Android SDK-functies die kunnen worden geretourneerd null , hebben nu een hogere kans op retourneren null. Zorg ervoor dat null deze functie-aanroepen worden beveiligd met controles.
• Functies waarop kan worden gecontroleerd, zoals clipboardManager.getPrimaryClipDescription(), moeten worden gecontroleerd via hun MAM-vervangende API's, zoals MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Alle afgeleide functies moeten worden aangeroepen naar hun superklasseversies.
• Vermijd het gebruik van API's op een dubbelzinnige manier. Als u bijvoorbeeld gebruikt Activity.startActivityForResult zonder het requestCode te controleren, wordt vreemd gedrag veroorzaakt.

Services

Het afdwingen van beleid kan van invloed zijn op interacties met de Android-service . Methoden die een afhankelijke serviceverbinding tot stand brengen, zoals Context.bindService mogelijk mislukken vanwege onderliggende beleidshandhaving in Service.onBind en kunnen resulteren in ServiceConnection.onNullBinding of ServiceConnection.onServiceDisconnected. Interactie met een tot stand gebrachte gebonden service kan een SecurityException genereren vanwege het afdwingen van beleid in Binder.onTransact.

Clients van gebonden services worden aangemoedigd om te controleren op uitzonderingen die door de service worden gegenereerd. Laat uitzonderingen niet doorgeven aan de rest van de clienttoepassing.

Afsluitcriteria

Nadat u de build-invoegtoepassing hebt geconfigureerd of het opdrachtregelprogramma hebt geïntegreerd in uw buildproces, controleert u of deze wordt uitgevoerd:

• Zorg ervoor dat uw build wordt gecompileerd en gebouwd.
• Configureer de report vlag, open vervolgens het rapportdocument en controleer of er vervangingen van klassen en methoden plaatsvinden:
  • Als u de invoegtoepassing gebruikt, volgt u de stappen in Rapportage.
  • Als u het opdrachtregelprogramma gebruikt, voegt u de --report vlag toe.
• Als u de invoegtoepassing gebruikt, configureert u de verify vlag en zorgt u ervoor dat er geen fouten optreden. Zie Verificatie.
• Controleer alle uitsluitingen (excludeProjects, excludeClassesen excludeVariants) in build.gradle. Controleer of elke uitsluiting noodzakelijk is en geen beveiligde gegevens behandelt. Historisch gezien treden veel fouten met gegevenslekken op vanwege te agressieve uitsluitingen.
• Start uw gecompileerde app zonder de Intune-bedrijfsportal geïnstalleerd. Meld u aan met een Microsoft Entra gebruiker die niet is gericht op app-beveiligingsbeleid. Controleer of de app werkt zoals verwacht.
  • Meld u af en herhaal deze test met de Intune-bedrijfsportal geïnstalleerd.

Veelgestelde vragen

Mijn app heeft de SDK eerder geïntegreerd zonder de build-invoegtoepassing; hoe kan ik de build-invoegtoepassing gebruiken?

Oudere versies van de Intune App SDK bevatten geen geautomatiseerde manier om klasse- en methodevervangingen uit te voeren. Ontwikkelaars moesten deze vervangingen handmatig uitvoeren in de broncode. Als uw app op deze manier is geïntegreerd, is het veilig om de build-invoegtoepassing of het buildhulpprogramma voor de opdrachtregel toe te passen. U hebt geen wijzigingen in de broncode nodig. In uw project moet de MAM SDK nog steeds als afhankelijkheid worden vermeld.

Volgende stappen

Nadat u alle afsluitcriteria hebt voltooid, gaat u door naar Fase 4: MAM Integration Essentials.