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

Článek
10/14/2024

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á Intune je aplikace integrovaná se sadou Intune App SDK. Intune správci můžou zásady ochrany aplikací snadno nasadit do aplikace spravované 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í aplikace.

Velkou část integrace sady Intune App SDK spočívá v nahrazení standardních tříd Androidu a volání metod Intune verzemi 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 metod v 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. SADA SDK. DownlevelStubs.aar: Tato funkce 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

Sada Intune App SDK je standardní knihovna Androidu bez externích závislostí. Microsoft. Intune. MAM. SADA 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 Androidu. Pokud chcete tuto závislost přidat do svého buildu, postupujte podle pokynů v dokumentaci k přidání AAR nebo JAR jako závislosti z Androidu .

Visual Studio

Balíček NuGet 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. SADA SDK.aar je vázána k vytváření odkazů jazyka C#, které jsou vymezeny na Microsoft.Intune.Mam obor 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 pravidla konfigurace 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ějí žá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é musí být dokončeny, než bude aplikace plně Intune povolena. 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 do značné míry závisí 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 sady 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")
    }
}

Pokud pak chcete použít modul plug-in, přidejte do build.gradle souboru pro vaši aplikaci a moduly dynamických funkcí 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 8.0 Intune App SDK 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
}

Konfigurace modulu dynamických funkcí

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

Vzhledem k technickým omezením rozhraní API používaných modulem plug-in Gradle je potřeba při transformaci tříd modulů dynamických funkcí znovu zpracovat třídy aplikací. Aby to bylo možné provést, měly by být všechny moduly funkcí nakonfigurované se stejnými nastaveními, pro kterou je aplikace navržená.

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

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 NuGet Intune App SDK pro .NET MAUI – Android se cíle automaticky naimportují do vaší aplikace při kompilaci.

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.jar se 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).

Po provedení automatického nahrazení sada Intune App SDK 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 toto nahrazení provést 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: Integrace MAM Essentials.

Sdílet prostřednictvím

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

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

Goals fáze

Pozadí

Stažení sady Intune App SDK

Co je v sadě SDK?

Odkazování na knihovny aplikací Intune

Android Studio

Visual Studio

ProGuard

Nástroje sestavení

Dopad na ladění

MAM v stacku

Jaký nástroj potřebuji?

Integrace s modulem plug-in buildu Gradle

Závislosti

Vyloučení

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

Vytváření sestav

Ověření

Přírůstková sestavení

Konfigurace modulu dynamických funkcí

Integrace s cíli .NET MAUI

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

Použití nástroje Command-Line

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

Nastavení APLIKACE MAM

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

Služby

Kritéria ukončení

Časté otázky

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

Další kroky

Váš názor

Další materiály