Intune App SDK voor Android - Aan de slag met MAM

Met de Microsoft Intune App SDK voor Android kunt u Intune app-beveiligingsbeleid opnemen in uw eigen Android-app Java/Kotlin. Dit beleid wordt ook wel MAM-beleid genoemd. Een door 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 beveiligingsbeleid implementeren op uw Intune beheerde app.

Opmerking

Deze gids is onderverdeeld in verschillende verschillende fasen. Begin met het doornemen van fase 1: plan de integratie.

Fase 3: Aan de slag met MAM

Fase doelen

  • Download de Intune App SDK.
  • Informatie over welke bestanden zijn opgenomen in de SDK van de Intune-app.
  • Verwijs in uw toepassing naar de Intune App SDK.
  • Configureer de Intune App Gradle Build-invoegtoepassing of gebruik het hulpprogramma voor het maken van 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 bestaat uit het vervangen van standaard Android-klassen en -methodeaanroepen door Intune versies van die klassen en methodeaanroepen. De SDK bevat buildhulpprogramma's die automatisch de meeste van deze vervangingen voor u uitvoeren. 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-plug-in, die helpt bij het integreren van de SDK.
  • CHANGELOG.md: Hier vindt u een record van de 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 over klassen die zijn afgeleid van MAMActivity, en de meeste apps hoeven deze niet op te nemen. De AAR bevat ProGuard-regels om alle klassen uit te sluiten.

Verwijzen naar Intune-app-bibliotheken

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 samen te werken met de Microsoft Intune Bedrijfsportal-app.

Android Studio

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

Visual Studio

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

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

De Microsoft.Intune. MAM. SDK.aar is gebonden aan het maken van C#-verwijzingen die binnen het bereik van de Microsoft.Intune.Mam naamruimte vallen.

ProGuard

Uw toepassing maakt mogelijk al gebruik van ProGuard (of een ander mechanisme voor verkleinen/verdoezelen) als buildstap. De SDK voor de Intune-app van Intune heeft ProGuard-configuratieregels die moeten worden opgenomen in deze buildstap. Met inbegrip van de . Zoals eerder is beschreven, integreert AAR in uw build automatisch de configuratie van de SDK in de ProGuard-stap, zodat de benodigde klassebestanden worden bewaard. Als u de . AAR, is er 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.

Bouwhulpmiddelen

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

De bouwtooling alleen is niet voldoende om uw toepassing volledig te integreren. De hulpprogramma's voeren alleen klasse- en methodevervangingen uit. Ze voeren geen complexere SDK-integraties uit, zoals Multi-identiteit, 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 geschikt is voor Intune. Lees de rest van deze documentatie zorgvuldig door voor integratiepunten die relevant zijn voor uw app.

Foutopsporing

De buildtooling voert vervangingen uit na compilatie. Met deze vervangingen worden sommige methodenamen gewijzigd. Als gevolg hiervan kan dit invloed hebben op foutopsporingsonderbrekingspunten die zijn ingesteld op methodenamen. Het kan zijn dat ze niet stoppen zoals verwacht. Onderbrekingspunten voor regelnummers worden niet beïnvloed.

MAM in de stapel

De integratie van Intune App SDK is sterk afhankelijk van klasse- en methodevervangingen. Hierdoor zijn stapeltraces overal in uw geheugen terug te zien mam . Als uw app geen account heeft waarop het beveiligingsbeleid voor apps is gericht, blijft al deze MAM-code inactief. Werkt bijvoorbeeld MAMActivity identiek aan en onMAMCreate identiek aan ActivityonCreate. Wanneer je in een stapel ziet mam , controleer je eerst:

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

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

Welk hulpprogramma heb ik nodig?

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

Als u uw app bouwt met .NET MAUI, raadpleegt u Integrating with the .NET MAUI Targets.

Als u een app hebt gemaakt met geen van de eerdere hulpprogramma's, raadpleegt u Integreren met het opdrachtregelprogramma.

Integratie met de Gradle Build-plug-in

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

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

Als u deze aan het klaspad wilt toevoegen, 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'

Standaard werkt de invoegtoepassing op project afhankelijkheden en externe bibliotheken. Dit heeft geen invloed op het compileren van tests.

Opmerking

Vanaf de 8.0-Intune App SDK is het niet langer mogelijk om bibliotheken selectief te verwerken. Alle bibliotheken worden verwerkt.

Afhankelijkheden

De Gradle-plug-in heeft een afhankelijkheid van Javassist, die beschikbaar moet worden gemaakt voor de afhankelijkheidsoplossing van Gradle. Javassist wordt alleen gebruikt tijdens de build bij het uitvoeren van de invoegtoepassing en er wordt geen Javassist-code toegevoegd aan uw app.

MAM SDK Javassist-versie
≥ 10.0.0 3.29.2-GA
≥ 7.0.0 3.27.0-GA
< 7.0.0 3.22.0-GA

Opmerking

Javassist-versies zijn mogelijk niet achterwaarts compatibel. Over het algemeen moet u de exacte versie gebruiken die door de SDK van de Intune-app wordt verwacht.

Compatibiliteitsmatrix

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

MAM SDK Android-versie Gradle Android Gradle Plugin Kotlin-versie Java-versie
10.0.0 14 8.2 8.2.2 1.9.25 17
11.0.0 15 8.7 8.6.1 2.0.21 17
12.0.0 16 8.11.1 8.9.1 2.1.21 17

Uitsluitingen

Er kunnen meer configuraties worden verstrekt 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 zeggen, geen bedrijfsgegevens verwerken of weergeven).

Uitsluitingen kunnen worden geconfigureerd voor verschillende bereiken:

  • excludeProjects maakt het mogelijk een lijst met Gradle-projecten uit te sluiten. Deze uitsluitingen zijn nuttig voor projecten die geen interface hebben met Android-bibliotheken of systeem-API's. Ze zijn ook handig voor projecten waarin geen bedrijfsgegevens worden verwerkt. 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 een interface heeft met Android-bibliotheken of systeem-API's, vermijdt u deze uitsluitingen.
  • excludeClasses Hiermee kunt u een lijst met klassen uitsluiten. Deze uitsluitingen zijn nuttig voor klassen die geen bedrijfsgegevens verwerken of presenteren. Welkomstschermen en onboarding-s Activityzijn bijvoorbeeld goede kandidaten. Een klasse kan niet worden uitgesloten als een van de superklassen wordt verwerkt.
  • excludeVariants Hiermee kunt u projectvarianten uitsluiten. Deze uitsluitingen kunnen verwijzen naar de naam van een volledige variant of naar een enkele smaak. Ze zijn vooral handig als u een niet-MAM-versie van uw app wilt maken. Als uw app bijvoorbeeld buildtypen debug heeft en release de smaken {noMAM, MAM} en {mock, production} heeft, kunt u het volgende opgeven:
    • noMAM om alle varianten met de noMAM-smaak uit te sluiten of
    • noMAMMockDebug om alleen die exacte variant uit te sluiten.

Voorzichtigheid

Uitsluitingen moeten niet lichtvaardig worden opgevat. Het onjuist toepassen van uitsluitingen kan leiden tot ernstige gegevenslekken in uw app. Valideer altijd het effect van een uitsluiting die u toepast.

Voorbeeld van een 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 zou de volgende effecten hebben:

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

Rapportage

De build-plug-in kan een html-rapport genereren van de wijzigingen die het aanbrengt. Als u het genereren van dit rapport wilt aanvragen, geeft u dit in het intunemam configuratieblok opreport = true. Als het rapport wordt gegenereerd, wordt het weggeschreven naar outputs/logs de map Build.

intunemam {
    report = true
}

Verificatie

De build-plug-in kan meer verificaties uitvoeren om te zoeken naar mogelijke fouten in verwerkingsklassen. Deze controles helpen bij het voorkomen van mogelijke door plug-ins veroorzaakte runtimefouten.

Als u wilt dat de verificatie wordt uitgevoerd in uw build, geeft u verify = true dit op in het intunemam configuratieblok. Dit kan enkele seconden toevoegen aan de tijd die de taak van de plugin in beslag neemt.

intunemam {
    verify = true
}

Over het algemeen vertegenwoordigt een verificatiefout een bug in de build-plugin. 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 dit in het intunemam configuratieblok opincremental = true. Met deze functie worden de prestaties van de build verbeterd doordat alleen de invoerbestanden die worden gewijzigd, worden verwerkt. De standaardconfiguratie hiervoor incremental is false.

intunemam {
    incremental = true
}

Configuratie van dynamische functiemodule

Dynamische functiemodules worden afzonderlijk van het app-project gebouwd. Als zodanig moeten dynamische functiemodules ook de Gradle Build-plug-in toepassen.

De Gradle-plug-in heeft technische beperkingen in de API's die het gebruikt. Vanwege deze beperkingen moeten app-klassen opnieuw worden verwerkt bij het transformeren van dynamische functiemoduleklassen. 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 dynamische functiemodule die klasse ook uitsluiten.

Integratie met de .NET MAUI-doelen

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

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

Integratie met het hulpprogramma voor het maken van de opdrachtregel

Het opdrachtregelprogramma is beschikbaar in de BuildTool map van de SDK-dropping. Het vervult dezelfde functie als de Gradle-plug-in en .NET-doelen die hierboven zijn beschreven. Het opdrachtregelprogramma kan echter worden geïntegreerd in aangepaste buildsystemen. Het is ingewikkelder om het hulpprogramma aan te roepen omdat het generieker is. Gebruik waar mogelijk de Gradle-invoegtoepassing of .NET-doelen.

Het hulpprogramma Command-Line gebruiken

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

Het hulpprogramma verwacht de volgende parameters.

Parameter Vereist Beschrijving
--input Ja Een door puntkomma's gescheiden lijst met JAR-bestanden en mappen met te wijzigen klassebestanden. Neem alle JAR's en mappen op die u wilt herschrijven.
--output Ja Een door puntkomma's gescheiden lijst met JAR-bestanden en mappen voor het opslaan van de gewijzigde klassen. Geef één uitvoervermelding per invoerinvoer op, in dezelfde volgorde.
--classpath Ja Klaspad bouwen. Deze indeling kan zowel JAR-bestanden als klassenmappen bevatten.
--processed Nee Een door puntkomma's gescheiden lijst van JAR-bestanden en mappen met klassen die al zijn verwerkt door een eerdere aanroep van het build-hulpprogramma.
--excludeClasses Nee Een door puntkomma's gescheiden lijst met de namen van klassen die moeten worden uitgesloten van herschrijven.
--report Nee Directory om een HTML-rapport over gewijzigde klassen naar te schrijven. Als dit niet is opgegeven, wordt er geen rapport geschreven.

De optionele --processed optie wordt gebruikt om incrementele builds in te schakelen. De set bestanden/mappen die hier wordt weergegeven, mag niet overeenkomen met de invoer- en klassepadlijsten.

Tip

Op Unix-achtige systemen is puntkomma een commando-scheidingsteken. Om te voorkomen dat de shell opdrachten splitst, moet u elke puntkomma met '' verwijderen of de volledige parameter tussen aanhalingstekens plaatsen.

Voorbeeld Command-Line het aanroepen van het hulpprogramma

> 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 zou de volgende effecten hebben:

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

Waarschuwing

Het buildprogramma biedt momenteel geen ondersteuning voor aar-bestanden. Als uw buildsysteem nog niet is uitgepakt classes.jar bij het verwerken van aar-bestanden, pak het dan uit voordat u het build-hulpprogramma aanroept.

MAMApplication instellen

Als uw app een subklasse maakt van android.app.Application, transformeert de build-plug-in of opdrachtregelprogramma uw toepassingsklasse.

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

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

Na het uitvoeren van automatische vervangingen handhaaft de Intune App SDK nog steeds het contract dat wordt geleverd door de Android-API. Foutvoorwaarden kunnen echter vaker worden geactiveerd als gevolg van het afdwingen van beleid. Deze aanbevolen procedures voor Android verkleinen de kans op fouten:

  • Android SDK-functies die kunnen terugkeren, null hebben nu een grotere kans om terug te keren null. Zorg ervoor dat null deze functieaanroepen worden beveiligd door controles.
  • Functies waarop kan worden gecontroleerd, bijvoorbeeld 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 een API op een dubbelzinnige manier. Gebruik bijvoorbeeld vreemd gedrag zonder Activity.startActivityForResult de requestCode oorzaken te controleren.

Services

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

Klanten van gebonden diensten worden aangemoedigd om te controleren op uitzonderingen die door de dienst worden gegenereerd. Zorg ervoor dat uitzonderingen niet worden doorgevoerd in de rest van de clienttoepassing.

Exit-criteria

Nadat u de invoegtoepassing voor het maken van builds hebt geconfigureerd of het opdrachtregelprogramma in het maakproces hebt geïntegreerd, controleert u of het programma goed wordt uitgevoerd:

  • Zorg ervoor dat je build met succes wordt gecompileerd en gebouwd.
  • Configureer de report markering, open vervolgens het rapportdocument en controleer of de klasse en methode worden vervangen:
    • 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 deze geen fouten produceert. Zie Verificatie.
  • Controleer alle uitsluitingen (excludeProjects, excludeClasses, en excludeVariants) in build.gradle. Controleer of elke uitsluiting noodzakelijk is en geen betrekking heeft op beveiligde gegevens. Historisch gezien treden veel fouten door gegevenslekken op vanwege te agressieve uitsluitingen.
  • Start de gecompileerde app zonder dat de Intune-bedrijfsportal is geïnstalleerd. Meld u aan met een Microsoft Entra-gebruiker die niet is gericht op het beveiligingsbeleid van apps. Controleer of de app werkt zoals verwacht.
    • Meld u af en herhaal deze test met de Intune-bedrijfsportal geïnstalleerd.

Veelgestelde vragen

Mijn app integreerde voorheen de SDK zonder de build-plug-in; hoe kan ik de build-plugin 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 broncode. Als je app op deze manier is geïntegreerd, kun je veilig de build-plug-in of het opdrachtregelbuild-hulpprogramma toepassen. U hoeft de broncode niet te wijzigen. In uw project moet de MAM SDK nog steeds worden vermeld als een afhankelijkheid.

Volgende stappen

Nadat u aan alle exitcriteria hebt voldaan, gaat u door naar fase 4: MAM Integration Essentials.

  • Last updated on