Intune App SDK pro Android – Začínáme s MAM

Sada Microsoft Intune App SDK pro Android umožňuje začlenit zásady ochrany aplikací Intune (označované také jako zásady APP nebo MAM) do nativní aplikace Java/Kotlin pro Android. Aplikace spravovaná v Intune je aplikace integrovaná se sadou Intune App SDK. Správci Intune můžou zásady ochrany aplikací snadno nasadit do aplikace spravované v Intune, když Intune aplikaci aktivně spravuje.

Poznámka

Tato příručka je rozdělená do několika různých fází. Začněte tím, že si projděte fázi 1: Plánování integrace.

Fáze 3: Začínáme s MAM

Goals fáze

• Stáhněte si sadu Intune App SDK.
• Zjistěte, jaké soubory jsou součástí sady Intune App SDK.
• Odkazujte na sadu Intune App SDK ve vaší aplikaci.
• Nakonfigurujte modul plug-in Intune App Gradle Build NEBO použijte nástroj pro sestavení příkazového řádku.
• Ověřte, že je sada Intune App SDK správně zahrnutá ve vašem buildu.

Pozadí

Teď, když vaše aplikace úspěšně integrovala knihovnu MSAL, je čas stáhnout sadu Intune App SDK a zahrnout ji do procesu sestavení vaší aplikace.

Velkou část integrace sady Intune App SDK spočívá v nahrazení standardních tříd Androidu a volání metod verzemi intune těchto tříd a volání metod. Sada SDK obsahuje nástroje pro sestavení, které za vás automaticky vytvoří většinu těchto nahrazení. Pokud se chcete o této nahrazování logiky dozvědět více, přečtěte si část nahrazení tříd a metodv příloze.

Stažení sady Intune App SDK

Informace o stažení sady SDK najdete v tématu Stažení souborů SADY SDK.

Co je v sadě SDK?

Sada Intune App SDK se skládá z následujících souborů:

• Microsoft.Intune.MAM.SDK.aar: Komponenty sady SDK s výjimkou souborů JAR knihovny podpory.
• com.microsoft.intune.mam.build.jar: Modul plug-in Gradle, který pomáhá integrovat sadu SDK.
• CHANGELOG.md: Poskytuje záznam o změnách provedených v jednotlivých verzích sady SDK.
• THIRDPARTYNOTICES.TXT: Oznámení o přiřazení, které potvrzuje kód třetí strany a/nebo OSS, který se zkompiluje do vaší aplikace.
• Microsoft.Intune.MAM.SDK.DownlevelStubs.aar: Tato služba AAR obsahuje zástupné procedury pro systémové třídy Androidu, které jsou přítomné jenom na novějších zařízeních, ale na které odkazují metody v MAMActivity. Novější zařízení tyto třídy zástupných procedur ignorují. Tato funkce AAR je nutná pouze v případě, že vaše aplikace provádí reflexi tříd odvozených z MAMActivitya většina aplikací ji nemusí zahrnovat. AAR obsahuje pravidla ProGuard pro vyloučení všech svých tříd.

Odkazování na knihovny aplikací Intune

Intune App SDK je standardní knihovna Androidu bez externích závislostí. Microsoft.Intune.MAM.SDK.aar obsahuje rozhraní potřebná k povolení zásad ochrany aplikací a kód potřebný pro spolupráci s aplikací Microsoft Intune Portál společnosti.

Android Studio

Microsoft.Intune.MAM.SDK.aar musí být zadaný jako odkaz na knihovnu Pro Android:

1. Otevřete projekt aplikace v Android Studiu a přejděte do modulu Nový soubor >>.
2. Vyberte Importovat . JAR/. Balíček AAR.
3. Vyberte Microsoft.Intune.MAM.SDK.aar a vytvořte modul pro . Typ souboru AAR .
4. Klikněte pravým tlačítkem na modul nebo moduly obsahující kód vaší aplikace a přejděte nakartu> Závislosti nastavení> modulu + ikona>Závislost modulu.
5. Vyberte modul AAR sady MAM SDK, který jste vytvořili, a vyberte OK. Přidáním tohoto odkazu zajistíte, že se modul při sestavování projektu zkompiluje se sadou MAM SDK.

Visual Studio

Balíček NuGet pro Intune App SDK pro .NET MAUI – Android se musí přidat jako závislost.

Postupujte podle postupu instalace a správy balíčků v sadě Visual Studio pomocí Správce balíčků NuGet.

Microsoft.Intune.MAM.SDK.aar je vázán k vytváření odkazů jazyka C#, které mají obor Microsoft.Intune.Mam názvů.

ProGuard

Vaše aplikace už může používat ProGuard (nebo jakýkoli jiný mechanismus zmenšení/obfuskace) jako krok sestavení. Sada Intune App SDK obsahuje konfigurační pravidla ProGuard, která musí být součástí tohoto kroku sestavení. Včetně . AAR ve vašem buildu, jak je popsáno výše, automaticky integruje konfiguraci sady SDK do kroku ProGuard, takže se zachovají potřebné soubory třídy. Pokud jste správně zahrnuli . AAR, není potřeba žádná jiná změna.

Microsoft Authentication Library (MSAL) se dodává s vlastní konfigurací ProGuard. Pokud vaše aplikace integruje KNIHOVNU MSAL, další podrobnosti najdete v dokumentaci k knihovně MSAL .

Nástroje sestavení

Sada SDK poskytuje nástroje pro sestavení (modul plug-in pro sestavení Gradle, cíle pro sestavení .NET a nástroj příkazového řádku), které automaticky provádějí nahrazení MAM. Tyto nástroje transformují soubory tříd vygenerované kompilací Javy; Původní zdrojový kód neupravují. Musíte použít modul plug-in Gradle, balíček NuGet .NET nebo nástroj příkazového řádku.

Samotné nástroje sestavení nestačí k plné integraci vaší aplikace. Nástroje provádějí pouze nahrazení tříd a metod . Neprovádí žádné složitější integrace sady SDK, jako jsou multi-identity, registrace zásad ochrany aplikací, zásady omezení přenosu dat mezi aplikacemi a zařízeními nebo umístěními cloudového úložiště nebo konfigurace MSAL, která se musí dokončit, než bude vaše aplikace plně povolená v Intune. Pečlivě si projděte zbývající část této dokumentace, kde najdete body integrace relevantní pro vaši aplikaci.

Dopad na ladění

Nástroje sestavení po kompilaci nahrazují, což změní názvy některých metod. V důsledku toho může být ovlivněno ladění zarážek nastavených pro názvy metod a nemusí se zastavit podle očekávání. Na zarážky čísel řádků to nemá vliv.

MAM v stacku

Vzhledem k tomu, že integrace sady Intune App SDK se do značné míry spoléhá na nahrazení tříd a metod, začnete sledovat mam trasování zásobníku. Pokud vaše aplikace nemá účet, na který cílí zásady ochrany aplikací, veškerý tento kód MAM leží v nečinnosti: MAMActivity bude fungovat stejně jako Activity, onMAMCreate bude fungovat stejně jako onCreateatd. Kdykoli se mam zobrazí v zásobníku, nejprve zkontrolujte:

• Cílí na účet zásady ochrany aplikací?
• Je Portál společnosti Intune nainstalovaný?

Pokud odpověď na obojí není "ano", kód MAM funguje jako jednoduché předávání.

Jaký nástroj potřebuji?

Pokud vytváříte aplikaci pomocí Gradle, přečtěte si téma Integrace s modulem plug-in buildu Gradle.

Pokud vytváříte aplikaci pomocí .NET MAUI, přečtěte si téma Integrace s cíli .NET MAUI.

Pokud aplikaci sestavíte pomocí žádné z výše uvedených možností, přečtěte si téma Integrace s nástrojem příkazového řádku.

Integrace s modulem plug-in buildu Gradle

Modul plug-in Intune App SDK se distribuuje jako součást sady SDK jako GradlePlugin/com.microsoft.intune.mam.build.jar.

Aby byl modul plug-in rozpoznán gradlem, musí být přidán do buildscript cesty ke třídě. Modul plug-in závisí na Javassistu, který musí být také přidán. Další informace o závislostech Javassist najdete v tématu Závislosti.

Pokud je chcete přidat do cesty ke třídě, přidejte do kořenového adresáře build.gradlenásledující:

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")
    }
}

Pak modul plug-in použijete tak, že do build.gradle souboru pro modul vaší aplikace přidáte následující:

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

Ve výchozím nastavení modul plug-in funguje se project závislostmi a externími knihovnami. Kompilace testů není ovlivněna.

Poznámka

Počínaje sadou Intune App SDK 8.0 už není možné selektivně zpracovávat knihovny. Všechny knihovny jsou zpracovány.

Závislosti

Poznámka

Musíte používat verzi 3.6.1 nebo novější modulu plug-in Pro Android Gradle a gradle verze 5.6.4 nebo novější.

Modul plug-in Gradle je závislý na Javassistu, který musí být dostupný pro řešení závislostí Gradle. Javassist se používá výhradně v době sestavení při spuštění modulu plug-in a do vaší aplikace se nepřidá žádný kód Javassist.

Poznámka

Verze Javassist nemusí být zpětně kompatibilní. Obecně byste měli použít přesnou verzi očekávanou sadou Intune App SDK:

• Intune App SDK ≥ 10.0.0 vyžaduje Javassist 3.29.2-GA
• Intune App SDK ≥ 7.0.0 vyžaduje Javassist 3.27.0-GA
• Intune App SDK < 7.0.0 vyžaduje Javassist 3.22.0-GA

Kromě toho při používání sady MAM SDK 8.0.0+ musíte zajistit, aby byla v konfiguraci Gradle nastavena následující:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Vyloučení

Mohou být poskytnuty další konfigurace, které z přepisů vyloučí konkrétní komponenty ve vaší aplikaci. Vyloučení jsou převážně užitečná pro komponenty, které nejsou relevantní pro MAM (tj. nezpracovávají ani nezobrazují podniková data).

Vyloučení je možné nakonfigurovat pro různé obory:

• excludeProjects umožňuje vyloučit seznam projektů Gradle. Tato vyloučení jsou užitečná pro projekty, které nejsou rozhraním knihoven Androidu nebo systémovými rozhraními API nebo nezpracovávají podniková data. Vhodným kandidátem může být například projekt, který obsahuje výhradně nativní kód pro provádění síťových operací na nízké úrovni. Pokud projekt široce spolupracuje s knihovnami Androidu nebo systémovými rozhraními API, měli byste se těmto vyloučením vyhnout.
• excludeClasses umožňuje vyloučit seznam tříd. Tato vyloučení jsou užitečná pro třídy, které nezpracovávají nebo prezentují podniková data. Dobrými kandidáty jsou například úvodní obrazovky a onboardingy Activity. Všimněte si, že třídu nelze vyloučit, pokud se zpracuje některá z jejích nadtříd.
• excludeVariants umožňuje vyloučit varianty projektu. Tato vyloučení můžou odkazovat buď na úplný název varianty, nebo na jednu příchuť. Jsou užitečné hlavně v případě, že chcete vytvořit aplikaci, která není součástí MAM. Pokud má vaše aplikace například typy debug sestavení a release s příchutěmi {noMAM, MAM} a {mock, production} můžete zadat následující:
  • noMAM k vyloučení všech variant s příchutí noMAM nebo
  • noMAMMockDebug vyloučit pouze přesnou variantu.

Upozornění

Vyloučení by se neměla brát na lehkou váhu. Nesprávné použití vyloučení může vést k závažnému úniku dat ve vaší aplikaci. Vždy ověřte dopad jakéhokoli vyloučení, které použijete.

Příklad částečného sestavení.gradle s vyloučeními

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

To by mohlo mít následující účinky:

• :product:FooLib se nepřepíše, protože je součástí excludeProjects
• :product:foo-project se přepíše, s výjimkou com.contoso.SplashActivitypříkazu , který se přeskočí, protože je v excludeClasses
• com.microsoft.bar:baz.1.0.0 se přepíše, protože všechny externí knihovny jsou zahrnuty ke zpracování.
• Varianty s příchutí noMAM se nepřepíšou.

Vytváření sestav

Modul plug-in sestavení může vygenerovat zprávu HTML o provedených změnách. Pokud chcete požádat o vygenerování této sestavy, zadejte report = true v intunemam bloku konfigurace. Pokud se sestava vygeneruje, zapíše se do outputs/logs adresáře sestavení.

intunemam {
    report = true
}

Ověření

Modul plug-in sestavení může spustit další ověření a vyhledat možné chyby ve třídách zpracování. Tyto kontroly pomáhají chránit před potenciálními chybami modulu runtime vyvolanými moduly plug-in.

Pokud chcete v sestavení požádat o ověření, zadejte verify = true v intunemam bloku konfigurace. To může k času, který úkol modulu plug-in zabral, přidat několik sekund.

intunemam {
    verify = true
}

Obecně platí, že selhání ověření představuje chybu v modulu plug-in sestavení. Pokud potřebujete pomoc s selháním, eskalujte problém s podporou Microsoftu. Pokud nemáte smlouvu o podpoře Microsoftu, otevřete problém na GitHubu.

Přírůstková sestavení

Pokud chcete povolit podporu přírůstkového sestavování, zadejte incremental = true v intunemam bloku konfigurace. Tato funkce zvyšuje výkon sestavení tím, že zpracovává pouze vstupní soubory, které se změnily. Výchozí konfigurace pro incremental je false.

intunemam {
    incremental = true
}

Integrace s cíli .NET MAUI

Cíle sady Intune App SDK se distribuují jako součást sady SDK jako Microsoft.Intune.Maui.Essentials.android.targets.

Po přidání balíčku Intune App SDK pro .NET MAUI – Android se cíle automaticky naimportují do vaší aplikace v době kompilace.

Integrace s nástrojem pro sestavení příkazového řádku

Nástroj pro sestavení příkazového řádku je k dispozici ve BuildTool složce vyřazení sady SDK. Provádí stejnou funkci jako výše popsané cíle modulu plug-in Gradle nebo .NET, ale dá se integrovat do vlastních systémů sestavení. Vzhledem k tomu, že je obecnější, je jeho volání složitější, takže by se měl použít modul plug-in Gradle nebo cíle .NET, kdykoli je to možné.

Použití nástroje Command-Line

Nástroj příkazového řádku lze vyvolat pomocí poskytnutých pomocných skriptů umístěných v adresáři BuildTool\bin .

Nástroj očekává následující parametry.

Parametr	Povinný	Popis
--input	Ano	Seznam souborů JAR a adresářů souborů třídy, které chcete upravit, s oddělovači středníkem. To by mělo zahrnovat všechny soubory JAR nebo adresáře, které chcete přepsat.
--output	Ano	Seznam souborů JAR a adresářů oddělených středníkem, do které se mají ukládat upravené třídy. Pro každou vstupní položku by měla být jedna výstupní položka a měly by být uvedené v uvedeném pořadí.
--classpath	Ano	Cesta ke třídě sestavení. Může obsahovat soubory JAR i adresáře tříd.
--processed	Ne	Seznam souborů JAR s oddělovači a adresářů obsahujících třídy, které již byly zpracovány předchozím vyvoláním nástroje sestavení.
--excludeClasses	Ne	Seznam oddělený středníkem obsahující názvy tříd, které by měly být vyloučeny z přepisu.
--report	Ne	Adresář pro zápis sestavy HTML o změněných tříd do. Pokud není zadáno, nezapíše se žádná sestava.

Volitelná --processed možnost se používá k povolení přírůstkových sestavení. Sada souborů nebo adresářů, které jsou zde uvedené, by měla být oddělená se vstupními seznamy a seznamy cest k třídám.

Tip

V systémech unix-like středník je oddělovač příkazů. Abyste zabránili rozdělení příkazů prostředí, nezapomeňte u každého středníku uvozovat znak "' nebo celý parametr zabalit do uvozovek.

Příklad vyvolání nástroje 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

To by mohlo mít následující účinky:

• adresář se product-foo-project přepíše na mam-build\product-foo-project
• bar.jar se přepíše na mam-build\libs\bar.jar
• zap.jarse nepřepíše, protože je uveden pouze v--classpath
• Třída com.contoso.SplashActivity se nepřepíše , i když je v --input

Upozornění

Nástroj pro sestavení v současné době nepodporuje soubory aar. Pokud váš systém sestavení při práci se soubory aar ještě neextrahuje classes.jar , budete to muset udělat před vyvoláním nástroje sestavení.

Nastavení APLIKACE MAM

Pokud vaše aplikace vytvoří podtřídu android.app.Application, pak modul plug-in sestavení / nástroj příkazového řádku transformuje vaši třídu aplikace.

Pokud vaše aplikace nemá podtřídu android.app.Application"android:name" , musíte nastavit "com.microsoft.intune.mam.client.app.MAMApplication" jako atribut ve značce AndroidManifest.xml<application>.

Doporučené osvědčené postupy pro Android

• Použijte nejnovější nástroje pro sestavení sady Android SDK.
• Odeberte všechny nepotřebné a nepoužívané knihovny (například android.support.v4).

Sada Intune App SDK i po provedení automatického nahrazení stále udržuje kontrakt poskytovaný rozhraním API pro Android. Podmínky selhání se ale můžou aktivovat častěji v důsledku vynucování zásad. Tyto osvědčené postupy pro Android sníží pravděpodobnost selhání:

• Funkce sady Android SDK, které se můžou vrátit null , teď mají vyšší pravděpodobnost, že vrátí null. Ujistěte se, že null kontroly chrání tato volání funkcí.
• Funkce, které je možné zkontrolovat, jako clipboardManager.getPrimaryClipDescription()je , je potřeba zkontrolovat prostřednictvím jejich náhradních rozhraní API MAM, jako MAMClipboard.getPrimaryClipDescription(clipboardManager)je .
• Všechny odvozené funkce musí volat prostřednictvím své verze supertřídy.
• Nepoužívejte rozhraní API nejednoznačným způsobem. Například použití Activity.startActivityForResult bez kontroly requestCode způsobí podivné chování.

Služby

Vynucení zásad může mít vliv na interakce se službou Androidu. Metody, které navazování vázaného připojení služby, například Context.bindService , můžou selhat kvůli základnímu vynucování zásad v Service.onBind systému a mohou vést k ServiceConnection.onNullBinding nebo ServiceConnection.onServiceDisconnected. Interakce se zavedenou vázanou službou může vyvolat chybu SecurityException kvůli vynucení zásad v Binder.onTransactsystému .

Klientům vázaných služeb se důrazně doporučuje, aby kontrolovali výjimky vyvolané službou, místo aby se výjimky šířily do zbytku klientské aplikace.

Kritéria ukončení

Jakmile nakonfigurujete modul plug-in sestavení nebo integrujete nástroj příkazového řádku do procesu sestavení, ověřte, že je úspěšně spuštěný:

• Ujistěte se, že se sestavení úspěšně zkompiluje a sestaví.
• report Nakonfigurujte příznak a pak otevřete dokument sestavy a potvrďte, že dochází k nahrazování tříd a metod:
  • Pokud používáte modul plug-in, postupujte podle kroků v tématu Vytváření sestav.
  • Pokud používáte nástroj příkazového řádku, zahrňte příznak --report .
• Pokud používáte modul plug-in, nakonfigurujte verify příznak a ujistěte se, že nedochází k chybám. Viz Ověření.
• Pečlivě zkontrolujte všechna vyloučení (excludeProjects, excludeClassesa excludeVariants) v build.gradle. Ověřte, že každé vyloučení je nezbytné a nezabývá chráněnými daty. V minulosti došlo k mnoha chybám úniku dat kvůli příliš agresivním vyloučením.
• Bez nainstalované Portál společnosti Intune spusťte zkompilovanou aplikaci, přihlaste se pomocí Microsoft Entra uživatele, na kterého zásady ochrany aplikací cílí, a ověřte, že aplikace funguje podle očekávání.
  • Odhlaste se a opakujte tento test s nainstalovaným Portál společnosti Intune.

Časté otázky

Moje aplikace dříve integroval sadu SDK bez modulu plug-in sestavení; jak můžu použít modul plug-in buildu?

Starší verze sady Intune App SDK neobsáhly žádný automatizovaný způsob, jak provádět nahrazování tříd a metod, a vývojáři museli tyto nahrazení provádět ručně ve zdrojovém kódu. Pokud se vaše aplikace dříve integrovala tímto způsobem, je bezpečné použít modul plug-in sestavení (nebo nástroj pro sestavení příkazového řádku) bez jakýchkoli úprav zdrojového kódu. V projektu musí být sada MAM SDK stále vypisovat jako závislost.

Další kroky

Po dokončení všech kritérií ukončení pokračujte fází 4: Základy integrace MAM.