Sdk d’application Intune pour Android - Prise en main de la gestion des applications mobiles

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

Étape 3 : Prise en main de la gestion des applications mobiles

Objectifs de la phase

• Téléchargez le Kit de développement logiciel (SDK) de l’application Intune.
• Découvrez les fichiers inclus dans le Kit de développement logiciel (SDK) de l’application Intune.
• Référencez le SDK d’application Intune 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 SDK d’application Intune est correctement inclus dans votre build.

Contexte

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

Une grande partie de l’intégration du SDK d’application Intune consiste à remplacer les classes Android standard et les appels de méthode par des versions Intune de ces classes et 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 SDK d’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 d’application Intune se compose des fichiers suivants :

• Microsoft.Intune.MAM.SDK.aar : composants 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 Portail d’entreprise Microsoft Intune.

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 DU SDK d’application Intune 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 Microsoft.Intune.Mam de 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és, 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 soit entièrement activée par Intune. 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) d’application Intune repose fortement sur les remplacements de classes et de méthodes, vous commencerez à voir mam les traces de votre pile. 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, commencez par vérifier :

• 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 d’application Intune 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.

Dépendances

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.

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.

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 Kit de développement logiciel (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 DU SDK d’application Intune 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.

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.

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

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 toujours 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 des services liés sont fortement encouragés à rechercher 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.
• Vérifiez 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.
• Si le portail d’entreprise Intune n’est pas 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 Kit de développement logiciel (SDK) d’application Intune 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 : Bases de l’intégration MAM.