Sada 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 do nativní aplikace Java/Kotlin pro Android. Tyto zásady se taky označují jako zásady MAM. Aplikace spravovaná Intune je aplikace, která je integrovaná se sadou Intune App SDK. Když službu Intune aktivně spravuje, můžou správci služby Intune do vaší aplikace spravované přes Intune snadno nasadit zásady ochrany aplikací.

Poznámka

Tento průvodce je rozdělen do několika odlišných fází. Začněte tím, že si projdete 1. fázi: Plánování integrace.

3. fáze: Začínáme s MAM

Cíle fází

• Stáhněte si sadu Intune App SDK.
• Zjistěte, jaké soubory jsou součástí sady Intune App SDK.
• Odkažte se ve své aplikaci na sadu Intune App SDK.
• 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á do vašeho buildu.

Pozadí

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

Velká část integrace sady Intune App SDK nahrazuje standardní třídy a volání metod Androidu Intune verzemi těchto tříd a volání metod. Sada SDK obsahuje nástroje pro sestavení, které automaticky vytvoří většinu těchto nahrazení za vás. Pokud se chcete dozvědět více o této logice nahrazení, podívejte se na část nahrazení tříd a metod v příloze.

Stažení sady Intune App SDK

Pokud si chcete stáhnout sadu SDK, přečtěte si téma Stažení souborů sady SDK.

Co je součástí sady SDK?

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

• Microsoft. Intune. MAM. SDK.aar: Součásti sady SDK s výjimkou souborů JAR knihovny podpory.
• com.microsoft.intune.mam.build.jar: Modul plug-in Gradle, který pomáhá při integraci sady SDK.
• CHANGELOG.md: Poskytuje záznam o změnách provedených v každé verzi sady SDK.
• Microsoft. Intune. MAM. Sada SDK. DownlevelStubs.aar: Tento Android Archive (AAR) obsahuje zástupné procedury pro systémové třídy Androidu, které jsou přítomné jenom na novějších zařízeních, ale odkazují na ně metody v MAMActivity. Novější zařízení tyto třídy zástupných procedur ignorují. Tato AAR je nezbytná jenom 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, která vylučují všechny jeho třídy.

Odkazování na knihovny aplikací Intune

Sada Intune App SDK je standardní knihovna Androidu bez externích závislostí. Microsoft. Intune. MAM. Soubor SDK.aar obsahuje rozhraní nezbytná pro povolení zásad ochrany aplikací. Obsahuje také 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 zadán jako odkaz na knihovnu Androidu. Pokud chcete tuto závislost přidat do buildu, postupujte podle pokynů v dokumentaci k přidání AAR nebo JAR jako závislosti z Androidu.

Visual Studio

Sada Intune App SDK pro .NET MAUI – balíček NuGet pro Android musí být přidána 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. Soubor SDK.aar je vázán na vytváření odkazů jazyka C#, které jsou vymezeny Microsoft.Intune.Mam na obor názvů.

ProGuard

Vaše aplikace už může používat ProGuard (nebo jakýkoli jiný mechanismus zmenšení nebo zmatení) jako krok sestavení. Sada Intune App SDK obsahuje pravidla konfigurace ProGuard, která musí být součástí tohoto kroku sestavení. Včetně rozhraní . AAR ve vašem sestavení, jak bylo popsáno výše, automaticky integruje konfiguraci sady SDK do kroku ProGuard, aby byly zachovány potřebné soubory třídy. Pokud jste zahrnuli přepínač . AAR, žádná jiná změna není potřeba.

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

Nástroje pro sestavení

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

Samotné nástroje pro sestavení nestačí k úplné integraci vaší aplikace. Nástroje provádějí pouze nahrazení tříd a metod . Neprovádějí žádné složitější integrace sady SDK, jako je více identit, registrace zásad ochrany aplikací, zásady pro omezení přenosu dat mezi aplikacemi a zařízeními nebo umístěními cloudových úložišť nebo konfigurace MSAL. Tyto integrace musíte dokončit, aby byla vaše aplikace plně povolená pomocí služby Intune. Ve zbývající části této dokumentace si pečlivě projděte integrační body, které jsou relevantní pro vaši aplikaci.

Ladění

Nástroje pro sestavení provádí nahrazení po kompilaci. Tato nahrazení změní názvy některých metod. V důsledku toho může být ovlivněno ladění zarážek nastavených u názvů metod. Nemusí se zastavit podle očekávání. Zarážky čísel řádků zůstanou nedotčené.

MAM v zásobníku

Integrace sady SDK aplikací Intune do značné míry spoléhá na nahrazení tříd a metod. Vzhledem k této závislosti vidíte mam trasování zásobníku v celém rozsahu. Pokud vaše aplikace nemá účet, na který cílí zásady ochrany aplikací, veškerý tento kód MAM leží nečinný. Funguje například MAMActivity stejně jako onMAMCreateActivityonCreate. Kdykoli uvidíte mam v zásobníku, nejprve zkontrolujte:

• Zaměřují se na účet zásady ochrany aplikací?
• Je nainstalovaný Portál společnosti Intune?

Pokud odpověď na obě otázky není "ano", kód MAM funguje jako jednoduchý průchod.

Jaký nástroj potřebuji?

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

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

Pokud aplikaci nevytváříte pomocí žádného z předchozích nástrojů, přečtěte si téma Integrace s nástrojem příkazového řádku.

Integrace s modulem plug-in Gradle Build

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

Aby byl plugin rozpoznán Gradle, musí být přidán do buildscript classpath. Plugin závisí na Javassist, který musí být také přidán. Další informace o závislosti Javassist naleznete v tématu Závislosti.

Chcete-li je 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")
    }
}

Pokud pak chcete modul plug-in použít, přidejte do build.gradle souboru pro moduly aplikace a dynamických funkcí následující:

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

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

Poznámka

Počínaje sadou SDK pro aplikace Intune 8.0 už není možné zpracovávat knihovny selektivně. Zpracovávají se všechny knihovny.

Závislosti

Modul plug-in Gradle má závislost na Javassist, která musí být k dispozici 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 není přidán žádný Javassist kód.

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

Poznámka

Verze Javassist nemusí být zpětně kompatibilní. Obecně byste měli použít přesnou verzi, kterou sada SDK pro aplikace Intune očekává.

Matice kompatibility

Modul plug-in sestavení sady MAM SDK je v souladu s požadavky na sestavení Androidu a tabulkami kompatibility. Verze, které zde nejsou uvedené, můžou, ale nemusí fungovat.

MAM SDK	Verze Androidu	Gradle	Android Gradle Plugin	Verze Kotlin	Verze Javy
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

Vyloučení

Je možné poskytnout další konfigurace, které vyloučí konkrétní komponenty ve vaší aplikaci z přepisů. Výjimky jsou užitečné hlavně pro komponenty, které nejsou pro MAM relevantní (to znamená, že nezpracovávají nebo nezobrazují podniková data).

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

• excludeProjects Umožňuje vyloučit seznam projektů Gradle. Tato vyloučení jsou užitečná pro projekty, které nejsou propojené s knihovnami Androidu nebo systémovými rozhraními API. Taky jsou užitečné pro projekty, které nezpracovávají podniková data. Vhodným kandidátem může být třeba projekt, který obsahuje výhradně nativní kód určený k provádění nízkoúrovňových síťových operací. Pokud je projekt široce propojen s knihovnami Androidu nebo systémovými rozhraními API, vyhněte se těmto vyloučením.
• excludeClasses Umožňuje vyloučit seznam tříd. Tato vyloučení jsou užitečná pro třídy, které nezpracovávají nebo neprezentují podniková data. Vhodnými kandidáty jsou například úvodní obrazovky a úvodní Activityobrazovky. Třídu nelze vyloučit, pokud je zpracována některá z jejích nadřazených tříd.
• excludeVariants Umožňuje vyloučit varianty projektu. Tato vyloučení můžou odkazovat buď na celý název varianty, nebo na jednu variantu. Jsou užitečné zejména v případě, že chcete vytvořit jinou variantu aplikace, než MAM. Pokud má například vaše aplikace typy debug sestavení a release s příchutěmi {noMAM, MAM} a {mock, production} můžete zadat:
  • noMAM vyloučit všechny varianty s příchutí noMAM nebo
  • noMAMMockDebug tak, že vyloučíte pouze tuto 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 vážnému úniku dat v aplikaci. Vždy ověřte účinek každého vyloučení, které použijete.

Příklad částečné build.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 mělo následující důsledky:

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

Vytváření sestav

Modul plug-in sestavení může vygenerovat zprávu HTML o provedených změnách. Chcete-li požádat o vygenerování tohoto reportu, uveďte report = true v konfiguračním bloku intunemam . Pokud je sestava vygenerována, 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 hledat možné chyby ve zpracování tříd. Tyto kontroly pomáhají zajistit ochranu před potenciálními selháními modulu runtime vyvolanými modulem plug-in.

Pokud chcete požadovat ověření v sestavení, zadejte verify = true to do konfiguračního bloku intunemam . To může přidat několik sekund k času, který zabere úkol modulu plug-in.

intunemam {
    verify = true
}

Obecně platí, že selhání ověření představuje chybu v modulu plug-in sestavení. Pokud potřebujete pomoc s neúspěchem, eskalujte problém s podporou Microsoftu. Pokud nemáte smlouvu s podporou společnosti Microsoft, otevřete problém GitHub.

Přírůstkové buildy

Chcete-li povolit podporu přírůstkového sestavování, zadejte incremental = true v konfiguračním bloku intunemam . Tato funkce zvyšuje výkon sestavení zpracováním pouze vstupních souborů, které se mění. Výchozí konfigurace pro incremental je false.

intunemam {
    incremental = true
}

Konfigurace dynamického modulu funkcí

Moduly dynamických funkcí se sestavují odděleně od projektu aplikace. Moduly dynamických funkcí jako takové také musí použít modul plug-in Gradle Build.

Modul plug-in Gradle má technická omezení v rozhraních API, která používá. Kvůli těmto omezením je potřeba při transformaci tříd dynamických funkcí modulu znovu zpracovat třídy aplikací. Pokud chcete zajistit, aby bylo možné toto opětovné zpracování provést, nakonfigurujte všechny moduly funkcí se stejným nastavením jako aplikace.

Pokud například aplikace vylučuje třídu, měl by modul dynamických funkcí vyloučit také tuto třídu.

Integrace s cíli .NET MAUI

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

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

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 dropu sady SDK. Provádí stejnou funkci jako modul plug-in Gradle a cíle .NET popsané výše. Nástroj příkazového řádku je však možné integrovat do vlastních sestavovacích systémů. Vzhledem k tomu, že je nástroj obecnější, je jeho vyvolání složitější. Kdykoli je to možné, používejte modul plug-in Gradle nebo cíle .NET.

Použití nástroje Command-Line

Nástroj příkazového řádku je možné 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říd, které se mají upravit, oddělený středníkem. Zahrňte všechny soubory JAR a adresáře, které chcete přepsat.
--output	Ano	Seznam souborů JAR a adresářů oddělený středníkem pro ukládání upravených tříd. Na každou vstupní položku zadejte jednu výstupní položku ve stejném pořadí.
--classpath	Ano	Cesta třídy sestavení. Může obsahovat jak soubory JAR, tak adresáře tříd.
--processed	Ne	Seznam souborů JAR a adresářů oddělených středníky obsahující třídy, které již byly zpracovány předchozím vyvoláním nástroje sestavení.
--excludeClasses	Ne	Seznam oddělený středníky obsahující názvy tříd, které by se měly vyloučit z přepisu.
--report	Ne	Directory to write an HTML report about modified classes to. Pokud není zadán, není napsána žádná zpráva.

Volitelná --processed možnost se používá k povolení přírůstkových sestavení. Sada zde uvedených souborů/adresářů by měla být nespojená se seznamy vstupů a cest ke třídám.

Tip

V systémech podobných Unixu je středník oddělovačem příkazů. Aby prostředí nerozdělovalo příkazy, nezapomeňte každý středník přeskočit znakem ', nebo celý parametr uzavřít do uvozovek.

Příklad Command-Line vyvolání nástroje

> 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 mělo následující důsledky:

• Adresář product-foo-project se přepíše na mam-build\product-foo-project
• bar.jar se přepíše na mam-build\libs\bar.jar
• zap.jar se nepřepíše , protože je jen v seznamu --classpath
• Třída com.contoso.SplashActivityse nepřepíše , ani když je v --input

Upozornění

Nástroj pro sestavení momentálně nepodporuje soubory AAR. Pokud váš systém sestavení ještě neextrahuje classes.jar při práci se soubory AAR, extrahujte ho před vyvoláním nástroje sestavení.

Nastavení MAMApplication

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

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

Doporučené doporučené postupy pro Android

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

Po provedení automatických nahrazení sada Intune App SDK stále udržuje kontrakt poskytnutý rozhraním Android API. Kvůli vynucení zásad se ale můžou stavy selhání spouštět častěji. Tyto doporučené postupy pro Android snižují pravděpodobnost selhání:

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

Služby

Vynucování zásad může mít vliv na interakce služby Android Service . Metody, které vytvářejí vázané připojení služby, jako je například Context.bindService může selhat kvůli základnímu vynucování zásad v Service.onBind a může vést k nebo ServiceConnection.onNullBindingServiceConnection.onServiceDisconnected. Interakce se zavedenou vázanou službou může způsobit SecurityException vynucování zásad v Binder.onTransactrozhraní .

Klientům vázaných služeb se doporučuje, aby zkontrolovali výjimky, které služba vyvolává. Nedovolte, aby se výjimky rozšířily do zbytku klientské aplikace.

Kritéria pro ukončení

Po konfiguraci modulu plug-in sestavení nebo integraci nástroje příkazového řádku do procesu sestavení ověřte, že úspěšně běží:

• Ujistěte se, že vaše sestavení se úspěšně zkompiluje a sestaví.
• Nakonfigurujte report příznak a pak otevřete dokument sestavy a potvrďte, že dochází k nahrazení tříd a metod:
  • Pokud používáte plugin, postupujte podle kroků v Hlášení.
  • Pokud používáte nástroj příkazového řádku, zahrňte --report tento příznak.
• Pokud používáte plugin, nakonfigurujte verify příznak a ujistěte se, že nevytváří chyby. Viz Ověření.
• Překontrolujte všechna vyloučení (excludeProjects, excludeClassesa excludeVariants) v build.gradle. Ověřte, že každé vyloučení je nezbytné a netýká se chráněných dat. V minulosti docházelo k mnoha chybám úniku dat kvůli příliš agresivním vyloučením.
• Bez nainstalovaného Portál společnosti Intune spusťte zkompilovanou aplikaci. Přihlaste se jako uživatel služby Microsoft Entra, na kterého necílí zásady ochrany aplikací. 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 integrovala sadu SDK bez modulu plug-in sestavení; Jak můžu použít modul plug-in sestavení?

Starší verze sady Intune App SDK neobsahovaly žádný automatizovaný způsob, jak provést nahrazení tříd a metod. Vývojáři museli tato nahrazení provést ručně ve zdrojovém kódu. Pokud je vaše aplikace integrovaná tímto způsobem, je bezpečné použít modul plug-in nebo nástroj pro sestavení příkazového řádku. Nepotřebujete žádné úpravy zdrojového kódu. V projektu musí být sada MAM SDK pořád uvedená jako závislost.

Další kroky

Po splnění všech výstupních kritérií pokračujte do fáze 4: MAM Integration Essentials.