SDK d’application Intune pour Android - Prise en main de GAM

Article
11/22/2024

Le SDK d’application Microsoft Intune pour Android vous permet d’incorporer Intune stratégies de protection des applications (également appelées stratégies APP ou GAM) dans votre application Android Java/Kotlin native. Une application gérée par Intune est intégrée au KIT de développement logiciel (SDK) Intune App. Intune administrateurs peuvent facilement déployer des stratégies de protection des applications sur votre application gérée par Intune lorsque Intune gère activement l’application.

Remarque

Ce guide est divisé en plusieurs étapes distinctes. Commencez par passer en revue l’étape 1 : Planifier l’intégration.

Étape 3 : Prise en main avec gam

Goals de phase

Téléchargez le Kit de développement logiciel (SDK) Intune App.
Découvrez les fichiers inclus dans le Kit de développement logiciel (SDK) Intune App.
Référencez le KIT de développement logiciel (SDK) Intune App dans votre application.
Configurez le plug-in de build Intune App Gradle OU utilisez l’outil de génération en ligne de commande.
Vérifiez que le KIT de développement logiciel (SDK) Intune App est correctement inclus dans votre build.

Arrière-plan

Maintenant que votre application a correctement intégré MSAL, il est temps de télécharger le KIT de développement logiciel (SDK) Intune App et de l’inclure dans le processus de génération de votre application.

Une grande partie de l’intégration du Kit de développement logiciel (SDK) Intune App consiste à remplacer les classes Android standard et les appels de méthode par des versions Intune de ces classes et de ces appels de méthode. Le Kit de développement logiciel (SDK) inclut des outils de génération qui effectuent automatiquement la plupart de ces remplacements pour vous. Si vous souhaitez en savoir plus sur cette logique de remplacement, consultez la section Remplacements de classes et de méthodes de l’annexe.

Télécharger le Kit de développement logiciel (SDK) de l’application Intune

Pour télécharger le Kit de développement logiciel (SDK), consultez Télécharger les fichiers sdk.

Qu’y a-t-il dans le KIT de développement logiciel (SDK) ?

Le SDK Intune App se compose des fichiers suivants :

Microsoft. Intune. MAM. SDK.aar : composants du SDK, à l’exception des fichiers JAR de la bibliothèque de support.
com.microsoft.intune.mam.build.jar : plug-in Gradle, qui facilite l’intégration du SDK.
CHANGELOG.md : fournit un enregistrement des modifications apportées à chaque version du Kit de développement logiciel (SDK).
THIRDPARTYNOTICES.TXT: avis d’attribution qui reconnaît le code tiers et/ou OSS qui sera compilé dans votre application.
Microsoft. Intune. MAM. SDK. DownlevelStubs.aar : ce fichier AAR contient des stubs pour les classes système Android qui sont présentes uniquement sur les appareils plus récents, mais qui sont référencées par des méthodes dans MAMActivity. Les appareils plus récents ignorent ces classes stub. Cette AAR est nécessaire uniquement si votre application effectue une réflexion sur les classes dérivées de MAMActivityet que la plupart des applications n’ont pas besoin de l’inclure. AAR contient des règles ProGuard pour exclure toutes ses classes.

Référencement des bibliothèques d’applications Intune

Le SDK d’application Intune est une bibliothèque Android standard sans dépendances externes. Microsoft. Intune. MAM. SDK.aar contient à la fois les interfaces nécessaires pour activer les stratégies de protection des applications et le code nécessaire pour interagir avec l’application Microsoft Intune Portail d'entreprise.

Android Studio

Microsoft. Intune. MAM. SDK.aar doit être spécifié en tant que référence de bibliothèque Android. Pour ajouter cette dépendance à votre build, suivez Ajouter votre fichier AAR ou JAR en tant que dépendance à partir de la documentation Android.

Visual Studio

Le package NuGet Intune App pour .NET MAUI - Android doit être ajouté en tant que dépendance.

Suivez le processus d’installation et de gestion des packages dans Visual Studio à l’aide du Gestionnaire de package NuGet.

Microsoft.Intune. MAM. SDK.aar est lié à créer des références C# qui sont limitées à l’espace de Microsoft.Intune.Mam noms.

ProGuard

Votre application peut déjà utiliser ProGuard (ou tout autre mécanisme de réduction/obfuscation) comme étape de génération. Le SDK d’application Intune a des règles de configuration ProGuard qui doivent être incluses dans cette étape de génération. Y compris le . AAR dans votre build, comme décrit ci-dessus, intègre automatiquement la configuration du SDK à l’étape ProGuard, de sorte que les fichiers de classe nécessaires sont conservés. Si vous avez correctement inclus . AAR, aucune autre modification n’est nécessaire.

La bibliothèque d’authentification Microsoft (MSAL) est fournie avec sa propre configuration ProGuard. Si votre application intègre MSAL, reportez-vous à la documentation MSAL pour plus d’informations.

Outils de génération

Le SDK fournit des outils de génération (un plug-in pour les builds Gradle, des cibles pour les builds .NET et un outil en ligne de commande) qui effectuent automatiquement des remplacements MAM. Ces outils transforment les fichiers de classe générés par la compilation Java ; ils ne modifient pas le code source d’origine. Vous devez utiliser le plug-in Gradle, le package NuGet .NET ou l’outil en ligne de commande.

Les outils de génération ne suffisent pas à eux seuls pour intégrer entièrement votre application. Les outils effectuent uniquement des remplacements de classes et de méthodes . Ils n’effectuent pas d’intégrations de SDK plus complexes telles que multi-identité, inscription à la stratégie de protection des applications, stratégie de limitation du transfert de données entre les applications et les emplacements de stockage d’appareil ou cloud, ou configuration MSAL, qui doit être effectuée avant que votre application ne soit entièrement Intune activée. Examinez attentivement le reste de cette documentation pour connaître les points d’intégration pertinents pour votre application.

Impact sur le débogage

Les outils de génération effectuent des remplacements après la compilation, ce qui modifie certains noms de méthodes. Par conséquent, le débogage des points d’arrêt définis sur les noms de méthodes peut être impacté et ne pas s’arrêter comme prévu. Les points d’arrêt des numéros de ligne ne sont pas affectés.

Gam dans la pile

Étant donné que l’intégration du Kit de développement logiciel (SDK) Intune App s’appuie fortement sur les remplacements de classes et de méthodes, vous commencerez à voir mam les traces de vos piles. Lorsque votre application n’a pas de compte ciblé avec des stratégies de protection des applications, tout ce code MAM est dormant : fonctionne de la même Activitymanière que MAMActivity , onMAMCreate fonctionne de la même onCreatemanière que , etc. Chaque fois que vous voyez mam dans une pile, case activée :

Le compte est-il ciblé par des stratégies de protection des applications ?
Le Portail d'entreprise Intune est-il installé ?

Sauf si la réponse aux deux est « oui », le code GAM agit comme un simple passage.

De quel outil ai-je besoin ?

Si vous générez votre application avec Gradle, consultez Intégration avec le plug-in De build Gradle

Si vous générez votre application avec .NET MAUI, consultez Intégration avec les cibles MAUI .NET.

Si vous créez votre application avec l’un des éléments ci-dessus, consultez Intégration à l’outil en ligne de commande.

Intégration avec le plug-in Gradle Build

Le plug-in sdk Intune App est distribué dans le cadre du SDK en tant que GradlePlugin/com.microsoft.intune.mam.build.jar.

Pour que le plug-in soit reconnu par Gradle, il doit être ajouté au buildscript classpath. Le plug-in dépend de Javassist, qui doit également être ajouté. Pour plus d’informations sur la dépendance Javassist, consultez Dépendances.

Pour les ajouter au classpath, ajoutez ce qui suit à votre racine 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")
    }
}

Ensuite, pour appliquer le plug-in, ajoutez ce qui suit au build.gradle fichier de votre application et modules de fonctionnalités dynamiques :

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

Par défaut, le plug-in fonctionne sur project les dépendances et les bibliothèques externes. La compilation des tests n’est pas affectée.

Remarque

À compter de la version 8.0 Intune App SDK, il n’est plus possible de traiter les bibliothèques de manière sélective. Toutes les bibliothèques sont traitées.

Dépendances

Remarque

Vous devez utiliser la version 3.6.1 ou ultérieure du plug-in Android Gradle et la version 5.6.4 ou ultérieure de Gradle.

Le plug-in Gradle a une dépendance vis-à-vis de Javassist, qui doit être mise à disposition pour la résolution de dépendances de Gradle. Javassist est utilisé uniquement au moment de la génération lors de l’exécution du plug-in et aucun code Javassist n’est ajouté à votre application.

Remarque

Les versions Javassist peuvent ne pas être rétrocompatibles. En règle générale, vous devez utiliser la version exacte attendue par le SDK Intune App :

Intune App SDK ≥ 10.0.0 nécessite Javassist 3.29.2-GA
Intune App SDK ≥ 7.0.0 nécessite Javassist 3.27.0-GA
Intune App SDK < 7.0.0 nécessite Javassist 3.22.0-GA

En outre, lorsque vous consommez le SDK MAM 8.0.0+, vous devez vous assurer que les éléments suivants sont définis dans votre configuration Gradle :

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Exclusions

Des configurations supplémentaires peuvent être fournies pour exclure des composants spécifiques de votre application des réécritures. Les exclusions sont principalement utiles pour les composants qui ne sont pas pertinents pour la gestion des applications mobiles (c’est-à-dire, ne gèrent pas ou n’affichent pas les données d’entreprise).

Les exclusions peuvent être configurées pour différentes étendues :

excludeProjects autorise l’exclusion d’une liste de projets Gradle. Ces exclusions sont utiles pour les projets qui ne s’interfacent pas avec les bibliothèques Android ou les API système et/ou ne gèrent pas les données d’entreprise. Par exemple, un projet qui contient exclusivement du code natif pour effectuer des opérations réseau de bas niveau peut être un bon candidat. Si un projet s’interface largement avec des bibliothèques Android ou des API système, ces exclusions doivent être évitées.
excludeClasses autorise l’exclusion d’une liste de classes. Ces exclusions sont utiles pour les classes qui ne gèrent pas ou ne présentent pas de données d’entreprise. Par exemple, les écrans de démarrage et les intégrations Activitysont de bons candidats. Notez qu’une classe ne peut pas être exclue si l’une de ses superclasses est traitée.
excludeVariants active l’exclusion des variantes de projet. Ces exclusions peuvent faire référence à un nom de variante complet ou à une seule saveur. Elles sont particulièrement utiles si vous souhaitez créer une version non MAM de votre application. Par exemple, si votre application a des types debug de build et release avec des saveurs {noMAM, MAM} et {mock, }, productionvous pouvez spécifier les éléments suivants :
- noMAM pour exclure toutes les variantes avec la saveur noMAM ou
- noMAMMockDebug pour exclure uniquement cette variante exacte.

Attention

Les exclusions ne doivent pas être prises à la légère. L’application incorrecte d’exclusions peut entraîner de graves fuites de données dans votre application. Vérifiez toujours l’impact de toute exclusion que vous appliquez.

Exemple de build.gradle partiel avec exclusions

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

Cela aurait les effets suivants :

:product:FooLib n’est pas réécrit, car il est inclus dans excludeProjects
:product:foo-project est réécrit, à l’exception de com.contoso.SplashActivity, qui est ignoré car il est dans excludeClasses
com.microsoft.bar:baz.1.0.0 est réécrit, car toutes les bibliothèques externes sont incluses pour le traitement.
Les variantes avec la noMAM saveur ne sont pas réécrites.

Reporting

Le plug-in de build peut générer un rapport html des modifications qu’il apporte. Pour demander la génération de ce rapport, spécifiez report = true dans le bloc de intunemam configuration. S’il est généré, le rapport est écrit outputs/logs dans le répertoire de build.

intunemam {
    report = true
}

Vérification

Le plug-in de build peut exécuter une vérification supplémentaire pour rechercher les erreurs possibles dans les classes de traitement. Ces vérifications permettent de vous protéger contre les défaillances potentielles du runtime induites par le plug-in.

Pour demander que la vérification soit effectuée dans votre build, spécifiez verify = true dans le bloc de intunemam configuration. Cela peut ajouter plusieurs secondes au temps nécessaire à la tâche du plug-in.

intunemam {
    verify = true
}

En règle générale, un échec de vérification représente un bogue dans le plug-in de build. Pour obtenir de l’aide en cas d’échec, réaffectez le problème avec le support Microsoft. Si vous n’avez pas de contrat de support Microsoft, ouvrez un problème GitHub.

Builds incrémentielles

Pour activer la prise en charge de la génération incrémentielle, spécifiez incremental = true dans le bloc de intunemam configuration. Cette fonctionnalité augmente les performances de génération en traitant uniquement les fichiers d’entrée qui ont été modifiés. La configuration par défaut pour incremental est false.

intunemam {
    incremental = true
}

Configuration du module de fonctionnalité dynamique

Les modules de fonctionnalités dynamiques sont générés séparément du projet d’application. Par conséquent, les modules de fonctionnalité dynamique doivent également appliquer le plug-in de build Gradle.

En raison des limitations techniques des API utilisées par le plug-in Gradle, les classes d’application doivent être retraitées lors de la transformation des classes de module de fonctionnalités dynamiques. Pour vous assurer que cela peut être fait, tous les modules de fonctionnalité doivent être configurés avec les mêmes paramètres que l’application pour laquelle ils sont conçus.

Par exemple, si une application exclut une classe, le module de fonctionnalité dynamique doit également exclure cette classe.

Intégration avec les cibles MAUI .NET

Les cibles du SDK d’application Intune sont distribuées dans le cadre du KIT de développement logiciel (SDK) en tant que Microsoft.Intune. Maui. Essentials.android.targets.

Les cibles sont automatiquement importées dans votre application au moment de la compilation une fois le package NuGet Intune App pour .NET MAUI - Android ajouté.

Intégration à l’outil de génération en ligne de commande

L’outil de génération en ligne de commande est disponible dans le BuildTool dossier de la suppression du SDK. Il remplit la même fonction que les cibles de plug-in Gradle/.NET détaillées ci-dessus, mais peut être intégré dans des systèmes de génération personnalisés. Comme il est plus générique, il est plus complexe à appeler. Par conséquent, les cibles du plug-in Gradle/.NET doivent être utilisées dans la mesure du possible.

Utilisation de l’outil Command-Line

L’outil en ligne de commande peut être appelé à l’aide des scripts d’assistance fournis situés dans le BuildTool\bin répertoire.

L’outil attend les paramètres suivants.

Paramètre	Obligatoire	Description
`--input`	Oui	Liste délimitée par des points-virgules de fichiers jar et de répertoires de fichiers de classe à modifier. Cela doit inclure tous les fichiers jar/répertoires que vous avez l’intention de réécrire.
`--output`	Oui	Liste délimitée par des points-virgules de fichiers jar et de répertoires pour stocker les classes modifiées. Il doit y avoir une entrée de sortie par entrée, et elles doivent être répertoriées dans l’ordre.
`--classpath`	Oui	Classpath de build. Il peut contenir à la fois des fichiers jar et des répertoires de classe.
`--processed`	Non	Liste délimitée par des points-virgules de fichiers jar et de répertoires contenant des classes qui ont déjà été traitées par un appel précédent de l’outil de génération.
`--excludeClasses`	Non	Liste délimitée par des points-virgules contenant les noms des classes qui doivent être exclues de la réécriture.
`--report`	Non	Répertoire dans lequel écrire un rapport HTML sur les classes modifiées. S’il n’est pas spécifié, aucun rapport n’est écrit.

L’option facultative --processed est utilisée pour activer les builds incrémentielles. L’ensemble de fichiers/répertoires répertoriés ici doit être disjoint avec les listes d’entrée et de classpath.

Conseil

Sur les systèmes de type Unix, un point-virgule est un séparateur de commandes. Pour éviter que l’interpréteur de commandes ne divise les commandes, veillez à placer chaque point-virgule dans une séquence d’échappement avec « » ou à encapsuler le paramètre complet entre guillemets.

Exemple d’appel de l’outil 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

Cela aurait les effets suivants :

le product-foo-project répertoire est réécrit en mam-build\product-foo-project
bar.jar est réécrit en mam-build\libs\bar.jar
zap.jar n’est pas réécrit, car il n’est répertorié que dans--classpath
La com.contoso.SplashActivity classe n’est pas réécrite, même si elle se trouve dans --input

Avertissement

Actuellement, l’outil de génération ne prend pas en charge les fichiers aar. Si votre système de build ne s’extrait classes.jar pas déjà lors du traitement des fichiers aar, vous devez le faire avant d’appeler l’outil de génération.

Définition de MAMApplication

Si votre application crée une sous-classe de android.app.Application, le plug-in de build/outil en ligne de commande transforme votre classe d’application.

Si votre application ne sous-classe android.app.Applicationpas , vous devez définir "com.microsoft.intune.mam.client.app.MAMApplication" comme attribut dans la "android:name" balise de <application> votre AndroidManifest.xml.

Meilleures pratiques Android recommandées

Utilisez les derniers outils de génération du KIT de développement logiciel (SDK) Android.
Supprimez toutes les bibliothèques inutiles et inutilisées (par exemple, android.support.v4).

Après avoir effectué des remplacements automatiques, le SDK d’application Intune conserve le contrat fourni par l’API Android. Toutefois, les conditions d’échec peuvent être déclenchées plus fréquemment en raison de l’application de la stratégie. Ces bonnes pratiques Android réduisent la probabilité d’échec :

Les fonctions du Kit de développement logiciel (SDK) Android qui peuvent retourner null ont désormais une plus grande probabilité de retourner null. Vérifiez que null les vérifications protègent ces appels de fonction.
Les fonctionnalités qui peuvent être vérifiées, telles que clipboardManager.getPrimaryClipDescription(), doivent être vérifiées via leurs API de remplacement MAM, telles que MAMClipboard.getPrimaryClipDescription(clipboardManager).
Toutes les fonctions dérivées doivent appeler à leurs versions de super classe.
Évitez d’utiliser une API de manière ambiguë. Par exemple, l’utilisation Activity.startActivityForResult sans vérification du entraîne un requestCode comportement étrange.

Services

L’application de la stratégie peut affecter les interactions du service Android. Les méthodes qui établissent une connexion de service liée telle que Context.bindService peuvent échouer en raison de l’application de stratégie sous-jacente dans Service.onBind et peuvent entraîner ServiceConnection.onNullBinding ou ServiceConnection.onServiceDisconnected. L’interaction avec un service lié établi peut lever un SecurityException en raison de l’application de la stratégie dans Binder.onTransact.

Les clients de services liés sont fortement encouragés à case activée pour les exceptions levées par le service plutôt que de laisser les exceptions se propager au reste de l’application cliente.

Critères de sortie

Une fois que vous avez configuré le plug-in de build ou intégré l’outil en ligne de commande dans votre processus de génération, vérifiez qu’il s’exécute correctement :

Assurez-vous que votre build est compilée et générée correctement.
Configurez l’indicateur report , puis ouvrez le document de rapport et vérifiez que des remplacements de classes et de méthodes se produisent :
- Si vous utilisez le plug-in, suivez les étapes décrites dans Rapports.
- Si vous utilisez l’outil en ligne de commande, incluez l’indicateur --report .
Si vous utilisez le plug-in, configurez l’indicateur verify et assurez-vous qu’il ne génère pas d’erreurs. Consultez Vérification.
Double case activée toutes les exclusions (excludeProjects, excludeClasseset excludeVariants) dans build.gradle. Vérifiez que chaque exclusion est nécessaire et ne traite pas des données protégées. Historiquement, de nombreuses erreurs de fuite de données se sont produites en raison d’exclusions trop agressives.
Sans le Portail d'entreprise Intune installé, lancez votre application compilée, connectez-vous avec un utilisateur Microsoft Entra qui n’est pas ciblé par la stratégie de protection des applications et vérifiez que l’application fonctionne comme prévu.
- Déconnectez-vous et répétez ce test avec le Portail d'entreprise Intune installé.

FAQ

Mon application a précédemment intégré le KIT de développement logiciel (SDK) sans le plug-in de build ; Comment puis-je utiliser le plug-in de build ?

Les versions antérieures du SDK Intune App n’incluaient aucun moyen automatisé d’effectuer des remplacements de classes et de méthodes, et les développeurs devaient effectuer ces remplacements manuellement dans le code source. Si votre application s’était précédemment intégrée de cette façon, il est sûr d’appliquer le plug-in de build (ou l’outil de génération en ligne de commande) sans aucune modification du code source. Votre projet doit toujours répertorier le KIT DE développement logiciel (SDK) MAM en tant que dépendance.

Étapes suivantes

Une fois que vous avez terminé tous les critères de sortie, passez à l’étape 4 : Essentials d’intégration MAM.

Partager via

SDK d’application Intune pour Android - Prise en main de GAM

Étape 3 : Prise en main avec gam

Goals de phase

Arrière-plan

Télécharger le Kit de développement logiciel (SDK) de l’application Intune

Qu’y a-t-il dans le KIT de développement logiciel (SDK) ?

Référencement des bibliothèques d’applications Intune

Android Studio

Visual Studio

ProGuard

Outils de génération

Impact sur le débogage

Gam dans la pile

De quel outil ai-je besoin ?

Intégration avec le plug-in Gradle Build

Dépendances

Exclusions

Exemple de build.gradle partiel avec exclusions

Reporting

Vérification

Builds incrémentielles

Configuration du module de fonctionnalité dynamique

Intégration avec les cibles MAUI .NET

Intégration à l’outil de génération en ligne de commande

Utilisation de l’outil Command-Line

Exemple d’appel de l’outil Command-Line

Définition de MAMApplication

Meilleures pratiques Android recommandées

Services

Critères de sortie

FAQ

Mon application a précédemment intégré le KIT de développement logiciel (SDK) sans le plug-in de build ; Comment puis-je utiliser le plug-in de build ?

Étapes suivantes

Commentaires

Ressources supplémentaires