Dela via

Intune App SDK för Android – Kom igång med MAM

  • Artikel

Med Microsoft Intune App SDK för Android kan du införliva Intune-appskyddsprinciper (även kallade APP- eller MAM-principer ) i din interna Java/Kotlin Android-app. Ett Intune-hanterat program är ett program som är integrerat med Intune App SDK. Intune-administratörer kan enkelt distribuera appskyddsprinciper till din Intune-hanterade app när Intune aktivt hanterar appen.

Obs!

Den här guiden är uppdelad i flera olika steg. Börja med att granska steg 1: Planera integreringen.

Steg 3: Komma igång med MAM

Etappmål

  • Ladda ned Intune App SDK.
  • Lär dig vilka filer som ingår i Intune App SDK.
  • Referera till Intune App SDK i ditt program.
  • Konfigurera Intune App Gradle Build Plugin ELLER använd kommandoradsverktyget.
  • Kontrollera att Intune App SDK ingår korrekt i din version.

Bakgrund

Nu när programmet har integrerat MSAL är det dags att ladda ned Intune App SDK och inkludera det i programmets byggprocess.

En stor del av integreringen av Intune App SDK är att ersätta Android-standardklasser och metodanrop med Intune-versioner av dessa klasser och metodanrop. SDK innehåller byggverktyg som automatiskt gör de flesta av dessa ersättningar åt dig. Om du vill veta mer om den här ersättningslogik kan du läsa avsnittet om klass- och metodbyten i tillägget.

Ladda ned Intune App SDK

Information om hur du laddar ned SDK finns i Ladda ned SDK-filerna.

Vad finns i SDK: et?

Intune App SDK består av följande filer:

  • Microsoft.Intune.MAM.SDK.aar: SDK-komponenterna, förutom JAR-filerna för supportbiblioteket.
  • com.microsoft.intune.mam.build.jar: Ett Gradle-plugin-program som hjälper dig att integrera SDK:t.
  • CHANGELOG.md: Innehåller en post med ändringar som gjorts i varje SDK-version.
  • THIRDPARTYNOTICES.TXT: Ett attributionsmeddelande som bekräftar tredjeparts- och/eller OSS-kod som kommer att kompileras till din app.
  • Microsoft.Intune.MAM.SDK.DownlevelStubs.aar: Denna AAR innehåller stubs för Android-systemklasser som endast finns på nyare enheter men som refereras till av metoder i MAMActivity. Nyare enheter ignorerar dessa stub-klasser. Denna AAR är bara nödvändig om din app utför reflektion över klasser som härleds från MAMActivity, och de flesta appar behöver inte inkludera den. AAR innehåller ProGuard-regler för att undanta alla dess klasser.

Referera till Intune-appbibliotek

Intune App SDK är ett Android-standardbibliotek utan externa beroenden. Microsoft.Intune.MAM.SDK.aar innehåller både de gränssnitt som krävs för att aktivera appskyddsprinciper och den kod som krävs för att samverka med Microsoft Intune-företagsportalappen.

Android Studio

Microsoft.Intune.MAM.SDK.aar måste anges som en Android-biblioteksreferens. Om du vill lägga till det här beroendet i din version följer du Lägga till din AAR eller JAR som ett beroende från Android-dokumentationen.

Visual Studio

Intune App SDK för .NET MAUI – Android NuGet-paketet måste läggas till som ett beroende.

Följ processen för att installera och hantera paket i Visual Studio med Hjälp av NuGet-pakethanteraren.

Microsoft.Intune.MAM.SDK.aar kommer att skapa C#-referenser som är begränsade till Microsoft.Intune.Mam namnområdet.

ProGuard

Ditt program kan redan använda ProGuard (eller någon annan krympande/fördunkkningsmekanism) som ett byggsteg. Intune App SDK har ProGuard-konfigurationsregler som måste ingå i det byggsteget. Inklusive . AAR i din version, enligt beskrivningen ovan, integrerar automatiskt SDK:ts konfiguration i ProGuard-steget, så att de nödvändiga klassfilerna behålls. Om du har inkluderat . AAR, ingen annan ändring krävs.

Microsoft Authentication Library (MSAL) levereras med en egen ProGuard-konfiguration. Mer information finns i MSAL-dokumentationen om din app integrerar MSAL.

Skapa verktyg

SDK tillhandahåller byggverktyg (ett plugin-program för Gradle-versioner, mål för .NET-versioner och ett kommandoradsverktyg) som utför MAM-ersättningar automatiskt. De här verktygen transformerar klassfilerna som genereras av Java-kompilering. de ändrar inte den ursprungliga källkoden. Du måste använda antingen Gradle-plugin-programmet, .NET NuGet-paketet eller kommandoradsverktyget.

Enbart byggverktyget räcker inte för att helt integrera ditt program. Verktygen utför endast klass- och metodbyten . De utför inte några mer komplexa SDK-integreringar, till exempel multiidentitet, registrering för appskyddsprincip, princip för att begränsa dataöverföring mellan appar och enheter eller molnlagringsplatser eller MSAL-konfiguration, som måste slutföras innan din app är helt Intune-aktiverad. Granska noggrant resten av den här dokumentationen för integreringspunkter som är relevanta för din app.

Påverkan på felsökning

Byggverktyget utför ersättningar efter kompileringen, vilket ändrar vissa metodnamn. Det innebär att felsökning av brytpunkter som angetts för metodnamn kan påverkas och inte stoppas som förväntat. Radnummer brytpunkter påverkas inte.

MAM i stacken

Eftersom Intune App SDK-integreringen är starkt beroende av klass- och metodbyten börjar du se mam i dina stackspårningar. När din app inte har med ett konto som är mål för appskyddsprinciper ligger all denna MAM-kod vilande: MAMActivity fungerar identiskt Activitymed , onMAMCreate fungerar identiskt onCreatemed osv. När du ser mam i en stack kontrollerar du först:

  • Är kontot mål för appskyddsprinciper?
  • Är Intune-företagsportalen installerad?

Om inte svaret på båda är "ja" fungerar MAM-koden som enkel genomströmning.

Vilket verktyg behöver jag?

Om du skapar din app med Gradle kan du läsa Integrera med Gradle Build-plugin-programmet

Om du skapar din app med .NET MAUI läser du Integrera med .NET MAUI-målen.

Om du skapar din app med inget av ovanstående kan du läsa Integrera med kommandoradsverktyget.

Integrera med Gradle Build-plugin-programmet

Plugin-programmet Intune App SDK distribueras som en del av SDK:t som GradlePlugin/com.microsoft.intune.mam.build.jar.

För att plugin-programmet ska kunna identifieras av Gradle måste det läggas till i buildscript klassökvägen. Plugin-programmet är beroende av Javassist, som också måste läggas till. Mer information om det javassistiska beroendet finns i Beroenden.

Lägg till dessa i klassökvägen genom att lägga till följande i roten 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")
    }
}

Om du sedan vill tillämpa plugin-programmet lägger du till följande i build.gradle filen för din app och dynamiska funktionsmoduler:

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

Som standard fungerar plugin-programmet på project beroenden och externa bibliotek. Testkompilering påverkas inte.

Obs!

Från och med 8.0 Intune App SDK går det inte längre att bearbeta bibliotek selektivt. Alla bibliotek bearbetas.

Beroenden

Obs!

Du måste använda version 3.6.1 eller senare av Plugin-programmet Android Gradle och version 5.6.4 eller senare av Gradle.

Gradle-plugin-programmet har ett beroende av Javassist, som måste göras tillgängligt för Gradles beroendematchning. Javassist används enbart vid byggtiden när plugin-programmet körs och ingen Javassist-kod läggs till i din app.

Obs!

Javassist-versioner kanske inte är bakåtkompatibla. I allmänhet bör du använda den exakta version som förväntas av Intune App SDK:

  • Intune App SDK ≥ 10.0.0 kräver Javassist 3.29.2-GA
  • Intune App SDK ≥ 7.0.0 kräver Javassist 3.27.0-GA
  • Intune App SDK < 7.0.0 kräver Javassist 3.22.0-GA

När du använder MAM SDK 8.0.0+ måste du dessutom se till att följande anges i Gradle-konfigurationen:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Undantag

Ytterligare konfigurationer kan tillhandahållas för att undanta specifika komponenter i din app från omskrivningar. Undantag är främst användbara för komponenter som inte är relevanta för MAM (dvs. inte hanterar eller visar företagsdata).

Undantag kan konfigureras för olika omfång:

  • excludeProjects tillåter exkludering av en lista över Gradle-projekt. Dessa undantag är användbara för projekt som inte samverkar med Android-bibliotek eller system-API:er och/eller inte hanterar företagsdata. Till exempel kan ett projekt som uteslutande innehåller intern kod för att utföra nätverksåtgärder på låg nivå vara en bra kandidat. Om ett projekt har ett brett gränssnitt med Android-bibliotek eller system-API:er bör dessa undantag undvikas.
  • excludeClasses tillåter exkludering av en lista över klasser. Dessa undantag är användbara för klasser som inte hanterar eller presenterar företagsdata. Till exempel är välkomstskärmar och onboardings Activitybra kandidater. Observera att en klass inte kan uteslutas om någon av dess superklasser bearbetas.
  • excludeVariants möjliggör exkluderande projektvarianter. Dessa undantag kan referera till antingen ett fullständigt variantnamn eller en enda smak. De är särskilt användbara om du vill skapa en icke-MAM-smak av din app. Om din app till exempel har byggtyper debug och release med smakerna {noMAM, MAM} och {mock, production} kan du ange följande:
    • noMAM för att utesluta alla varianter med noMAM-smak eller
    • noMAMMockDebug för att endast utesluta den exakta varianten.

Försiktighet

Undantag bör inte tas lättvindigt. Felaktig tillämpning av undantag kan leda till allvarliga dataläckor i din app. Verifiera alltid effekten av eventuella undantag som du tillämpar.

Exempel på partiell build.gradle med undantag

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

Detta skulle ha följande effekter:

  • :product:FooLib skrivs inte om eftersom den ingår i excludeProjects
  • :product:foo-project skrivs om, förutom com.contoso.SplashActivity, som hoppas över eftersom den finns i excludeClasses
  • com.microsoft.bar:baz.1.0.0 skrivs om eftersom alla externa bibliotek ingår för bearbetning.
  • Varianter med smaken noMAM skrivs inte om.

Rapportering

Build-plugin-programmet kan generera en HTML-rapport över de ändringar som den gör. Om du vill begära generering av den här rapporten anger du report = true i konfigurationsblocket intunemam . Om den genereras skrivs rapporten till outputs/logs i byggkatalogen.

intunemam {
    report = true
}

Kontroll

Build-plugin-programmet kan köra ytterligare verifiering för att söka efter möjliga fel i bearbetningsklasser. Dessa kontroller hjälper till att skydda mot potentiella körningsfel som orsakas av plugin-program.

Om du vill begära verifiering utförs i bygget anger du verify = true i konfigurationsblocket intunemam . Detta kan lägga till flera sekunder till den tid det tar för plugin-programmets uppgift.

intunemam {
    verify = true
}

I allmänhet representerar ett verifieringsfel en bugg i plugin-programmet för bygget. Om du vill ha hjälp med ett fel eskalerar du problemet med Microsoft-supporten. Om du inte har något Microsoft-supportkontrakt öppnar du ett GitHub-problem.

Inkrementella versioner

Om du vill aktivera stöd för att skapa stegvis anger du incremental = true i konfigurationsblocket intunemam . Den här funktionen ökar byggprestandan genom att endast bearbeta de indatafiler som har ändrats. Standardkonfigurationen för incremental är false.

intunemam {
    incremental = true
}

Konfiguration av modul för dynamisk funktion

Dynamiska funktionsmoduler skapas separat från appprojektet. Därför måste dynamiska funktionsmoduler också tillämpa Plugin-programmet för Gradle-kompileringen.

På grund av tekniska begränsningar i DE API:er som används av Gradle-plugin-programmet måste appklasser bearbetas på nytt när du transformerar modulklasser för dynamiska funktioner. För att säkerställa att detta kan göras bör alla funktionsmoduler konfigureras med samma inställningar som den app som den är utformad för.

Om en app till exempel exkluderar en klass bör modulen för dynamiska funktioner även undanta den klassen.

Integrera med .NET MAUI-målen

Intune App SDK-målen distribueras som en del av SDK:t som Microsoft.Intune.Maui.Essentials.android.targets.

Målen importeras automatiskt till ditt program vid kompileringstillfället när Intune App SDK för .NET MAUI – Android NuGet-paketet har lagts till.

Integrera med kommandoradsverktyget

Kommandoradsverktyget är tillgängligt i BuildTool mappen för SDK-släppet. Den utför samma funktion som Gradle-plugin-programmet/.NET-målen som beskrivs ovan, men kan integreras i anpassade byggsystem. Eftersom det är mer allmänt är det mer komplext att anropa, så Gradle-plugin-programmet/.NET-målen bör användas när det är möjligt.

Använda Command-Line-verktyget

Kommandoradsverktyget kan anropas med hjälp av de hjälpskript som finns i BuildTool\bin katalogen.

Verktyget förväntar sig följande parametrar.

Parameter Obligatoriskt Beskrivning
--input Ja En semikolonavgränsad lista över jar-filer och kataloger för klassfiler som ska ändras. Detta bör innehålla alla jars/kataloger som du tänker skriva om.
--output Ja En semikolonavgränsad lista över jar-filer och kataloger som de ändrade klasserna ska lagras i. Det bör finnas en utdatapost per indatapost och de bör anges i ordning.
--classpath Ja Byggklassökvägen. Detta kan innehålla både jar-filer och klasskataloger.
--processed Nej En semikolonavgränsad lista över jar-filer och kataloger som innehåller klasser som redan har bearbetats av ett tidigare anrop av byggverktyget.
--excludeClasses Nej En semikolonavgränsad lista som innehåller namnen på de klasser som ska undantas från omskrivning.
--report Nej Katalog som du vill skriva en HTML-rapport om ändrade klasser till. Om inget anges skrivs ingen rapport.

Det valfria --processed alternativet används för att aktivera inkrementella versioner. Den uppsättning filer/kataloger som anges här bör vara åtskilda från indata- och klassökvägslistorna.

Tips

På Unix-liknande system är semikolon en kommandoavgränsare. Undvik att gränssnittet delar upp kommandon genom att undvika varje semikolon med eller omsluta den fullständiga parametern inom citattecken.

Exempel på Command-Line tool-anrop

> 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

Detta skulle ha följande effekter:

  • katalogen skrivs product-foo-project om till mam-build\product-foo-project
  • bar.jar skrivs om till mam-build\libs\bar.jar
  • zap.jar skrivs inte om eftersom den bara visas i --classpath
  • Klassen com.contoso.SplashActivity skrivs inte om även om den finns i --input

Varning

Build-verktyget stöder för närvarande inte aar-filer. Om byggsystemet inte redan extraherar classes.jar när du hanterar aar-filer måste du göra det innan du anropar byggverktyget.

Ange MAMApplication

Om din app skapar en underklass av android.app.Applicationomvandlas programklassen av build-plugin-verktyget/kommandoradsverktyget.

Om din app inte är underklass android.app.Applicationmåste du ange "com.microsoft.intune.mam.client.app.MAMApplication" som attribut i taggen "android:name" AndroidManifest.xml<application>.

  • Använd de senaste Android SDK-byggverktygen.
  • Ta bort alla onödiga och oanvända bibliotek (till exempel android.support.v4).

När du har utfört automatiska ersättningar underhåller Intune App SDK fortfarande det kontrakt som tillhandahålls av Android-API:et. Feltillstånd kan dock utlösas oftare på grund av principtillämpning. Dessa metodtips för Android minskar sannolikheten för fel:

  • Android SDK-funktioner som kan returneras null har nu högre sannolikhet att nullreturnera . Se till att null kontroller skyddar dessa funktionsanrop.
  • Funktioner som kan kontrolleras, till exempel clipboardManager.getPrimaryClipDescription(), måste kontrolleras via deras MAM-ersättnings-API:er, till exempel MAMClipboard.getPrimaryClipDescription(clipboardManager).
  • Alla härledda funktioner måste anropa sina superklassversioner.
  • Undvik att använda api:et på ett tvetydigt sätt. Om du till exempel använder Activity.startActivityForResult utan att kontrollera requestCode kommer det att orsaka konstigt beteende.

Tjänster

Principtillämpning kan påverka Android-tjänstens interaktioner. Metoder som upprättar en bunden tjänstanslutning, till exempel Context.bindService kan misslyckas på grund av underliggande principtillämpning i Service.onBind och kan resultera i ServiceConnection.onNullBinding eller ServiceConnection.onServiceDisconnected. Att interagera med en etablerad bunden tjänst kan utlösa en SecurityException på grund av principtillämpning i Binder.onTransact.

Klienter med bundna tjänster uppmanas starkt att söka efter undantag som genereras av tjänsten i stället för att låta undantag spridas till resten av klientprogrammet.

Avslutsvillkor

När du antingen har konfigurerat plugin-programmet eller integrerat kommandoradsverktyget i byggprocessen kontrollerar du att det körs:

  • Se till att bygget kompileras och byggs korrekt.
  • report Konfigurera flaggan och öppna sedan rapportdokumentet och bekräfta att klass- och metodbyten sker:
    • Om du använder plugin-programmet följer du stegen i Rapportering.
    • Ta med flaggan om du använder kommandoradsverktyget --report .
  • Om du använder plugin-programmet konfigurerar du verify flaggan och ser till att den inte genererar fel. Se Verifiering.
  • Dubbelkolla alla undantag (excludeProjects, excludeClassesoch excludeVariants) i build.gradle. Bekräfta att varje undantag är nödvändigt och inte hanterar skyddade data. Historiskt sett har många dataläckagefel inträffat på grund av överaggressiva undantag.
  • Utan intune-företagsportalen installerad startar du din kompilerade app, loggar in med en Microsoft Entra-användare som inte är mål för appskyddsprincipen och bekräftar att appen fungerar som förväntat.
    • Logga ut och upprepa det här testet med Intune-företagsportalen installerad.

Vanliga frågor och svar

Min app integrerade tidigare SDK utan plugin-programmet build; hur kan jag använda plugin-programmet för bygget?

Äldre versioner av Intune App SDK innehöll inget automatiserat sätt att utföra klass- och metodbyten, och utvecklare behövde utföra dessa ersättningar manuellt i källkoden. Om din app tidigare hade integrerats på det här sättet är det säkert att använda plugin-programmet för bygget (eller kommandoradsverktyget) utan några ändringar i källkoden. Ditt projekt måste fortfarande lista MAM SDK som ett beroende.

Nästa steg

När du har slutfört alla avslutsvillkor fortsätter du till steg 4: MAM Integration Essentials.