Share via

Intune App SDK voor Android - Aan de slag met MAM

  • Artikel

Met de Microsoft Intune App SDK voor Android kunt u intune-app-beveiligingsbeleid (ook wel APP - of MAM-beleid genoemd) opnemen in uw systeemeigen Java/Kotlin Android-app. Een door Intune beheerde toepassing is een toepassing die is geïntegreerd met de Intune App SDK. Intune-beheerders kunnen eenvoudig app-beveiligingsbeleid implementeren in uw door Intune beheerde app wanneer Intune de app actief beheert.

Opmerking

Deze handleiding is onderverdeeld in verschillende fasen. Bekijk eerst Fase 1: De integratie plannen.

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 buildprogramma 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.
  • THIRDPARTYNOTICES.TXT: een vermeldingsmelding die de code van derden en/of OSS erkent die in uw app wordt gecompileerd.
  • Microsoft.Intune.MAM.SDK.DownlevelStubs.aar: Deze 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.

Verwijzen naar Intune-app-bibliotheken

De Intune App SDK is een standaard-Android-bibliotheek zonder externe afhankelijkheden. Microsoft.Intune.MAM.SDK.aar bevat zowel de interfaces die nodig zijn voor het inschakelen van app-beveiligingsbeleid als de code die nodig is om te kunnen samenwerken 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.

Microsoft.Intune.MAM.SDK.aar is gebonden aan het maken van C#-verwijzingen die zijn afgestemd 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 heeft ProGuard-configuratieregels die moeten worden opgenomen in die buildstap. Inclusief de . AAR in uw build integreert, zoals hierboven beschreven, automatisch de configuratie van de SDK in de ProGuard-stap, zodat de benodigde klassebestanden worden bewaard. Als u de juiste gegevens 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, die moet worden voltooid voordat uw app volledig is ingeschakeld met Intune. Raadpleeg de rest van deze documentatie zorgvuldig voor integratiepunten die relevant zijn voor uw app.

Impact op foutopsporing

De buildtooling voert vervangingen uit na compilatie, waardoor sommige methodenamen worden gewijzigd. Als gevolg hiervan kunnen onderbrekingspunten voor foutopsporing die zijn ingesteld op methodenamen, worden beïnvloed en niet worden gestopt zoals verwacht. Onderbrekingspunten voor regelnummers worden niet beïnvloed.

MAM in de stack

Omdat de Intune App SDK-integratie sterk afhankelijk is van vervangingen van klassen en methoden, ziet mam u in uw stack traceringen. Wanneer uw app geen account heeft dat is gericht op app-beveiligingsbeleid, ligt al deze MAM-code inactief: MAMActivity werkt identiek aan Activity, onMAMCreate werkt identiek aan onCreate, enzovoort. 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 bovenstaande, raadpleegt u Integreren met het opdrachtregelprogramma.

Integreren met de Gradle Build-invoegtoepassing

De Intune App SDK-invoegtoepassing wordt gedistribueerd als onderdeel van de SDK 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.

Opmerking

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

Afhankelijkheden

Opmerking

U moet versie 3.6.1 of hoger van de Android Gradle-invoegtoepassing en versie 5.6.4 of hoger van Gradle gebruiken.

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.

Opmerking

Javassist-versies zijn mogelijk niet compatibel met eerdere versies. Over het algemeen moet u de exacte versie gebruiken die wordt verwacht door de Intune App SDK:

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

Wanneer u MAM SDK 8.0.0+ gebruikt, moet u er bovendien voor zorgen dat het volgende is ingesteld in uw Gradle-configuratie:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Uitsluitingen

Er kunnen aanvullende 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 (bijvoorbeeld het verwerken of weergeven van bedrijfsgegevens).

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 en/of 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 interface heeft met Android-bibliotheken of systeem-API's, moeten deze uitsluitingen worden vermeden.
  • 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. Houd er rekening mee dat een klasse niet kan 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.

Voorzichtigheid

Uitsluitingen moeten niet licht worden genomen. Het onjuist toepassen van uitsluitingen kan leiden tot ernstige gegevenslekken in uw app. Valideer altijd de impact van een uitsluiting die u toepast.

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 in outputs/logs de buildmap.

intunemam {
    report = true
}

Verificatie

De build-invoegtoepassing kan aanvullende verificatie 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 prestaties van de build door alleen de gewijzigde invoerbestanden te verwerken. 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.

Vanwege technische beperkingen in de API's die worden gebruikt door de Gradle-invoegtoepassing, moeten app-klassen opnieuw worden verwerkt bij het transformeren van dynamische functiemoduleklassen. Om ervoor te zorgen dat dit kan worden gedaan, moeten alle functiemodules worden geconfigureerd met dezelfde instellingen als de app waarvoor deze is ontworpen.

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 gedistribueerd als onderdeel van de SDK 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/.NET-doelen die hierboven zijn beschreven, maar kan worden geïntegreerd in aangepaste buildsystemen. Omdat het algemener is, is het complexer om aan te roepen, dus de Gradle-invoegtoepassing/ .NET-doelen moeten waar mogelijk worden gebruikt.

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.

Parameter Vereist Beschrijving
--input Ja Een door puntkomma's gescheiden lijst met JAR-bestanden en mappen van klassebestanden die u wilt wijzigen. Dit moet alle jar's/mappen bevatten die u wilt herschrijven.
--output Ja Een door puntkomma's gescheiden lijst met JAR-bestanden en mappen om de gewijzigde klassen in op te slaan. Er moet één uitvoervermelding per invoervermelding zijn en deze moeten op volgorde worden weergegeven.
--classpath Ja Het buildklassepad. Deze kan zowel jars als klassemappen bevatten.
--processed Nee Een door puntkomma's gescheiden lijst met JAR-bestanden en mappen met klassen die al zijn verwerkt door een eerdere aanroep van het buildhulpprogramma.
--excludeClasses Nee Een door puntkomma's gescheiden lijst met de namen van de klassen die moeten worden uitgesloten van herschrijven.
--report Nee Map 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 worden vermeld, moet niet aan elkaar worden gekoppeld met de invoer- en classpath-lijsten.

Tip

Op Unix-achtige systemen is een puntkomma een opdrachtscheidingsteken. Als u wilt voorkomen dat de shell opdrachten splitst, moet u elke puntkomma met '' laten ontsnappen of de volledige parameter tussen aanhalingstekens plaatsen.

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

Waarschuwing

Het build-hulpprogramma biedt momenteel geen ondersteuning voor aar-bestanden. Als uw buildsysteem nog niet wordt geëxtraheerd classes.jar wanneer u met aar-bestanden werkt, moet u dit doen voordat u het build-hulpprogramma aanroept.

MAMApplication instellen

Als uw app een subklasse van android.app.Applicationmaakt, transformeert de build-invoegtoepassing/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.

  • 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 Activity.startActivityForResult bijvoorbeeld gebruikt zonder de requestCode te controleren, leidt dit tot vreemd gedrag.

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 , kunnen mislukken vanwege het afdwingen van onderliggend beleid 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 sterk aangeraden om te controleren op uitzonderingen die door de service worden gegenereerd, in plaats van uitzonderingen door te geven 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 zijn er veel fouten met gegevenslekken opgetreden vanwege te agressieve uitsluitingen.
  • Als de Intune-bedrijfsportal niet is geïnstalleerd, start u de gecompileerde app, meldt u zich aan met een Microsoft Entra-gebruiker die niet onder het app-beveiligingsbeleid valt en controleert u of de app werkt zoals verwacht.
    • Afmelden en deze test herhalen terwijl de Intune-bedrijfsportal is 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 eerder op deze manier was geïntegreerd, is het veilig om de build-invoegtoepassing (of het build-hulpprogramma voor de opdrachtregel) toe te passen zonder wijzigingen in de broncode. In uw project moet de MAM SDK nog steeds als afhankelijkheid worden vermeld.

Volgende stappen

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