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 dans votre application Android Java/Kotlin native. Ces stratégies sont également appelées stratégies GAM. Une application gérée par Intune est intégrée au KIT de développement logiciel (SDK) Intune App. Lorsque Intune gère activement l’application, les administrateurs Intune peuvent facilement déployer des stratégies de protection des applications sur votre application gérée par Intune.

Étape 3 : Prise en main avec gam

Objectifs de la 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).
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar : ce Archive Android (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 les interfaces nécessaires à l’activation des stratégies de protection des applications. Il contient également 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 précédemment, 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 inclus le . 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. Vous devez effectuer ces intégrations 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.

Débogage

Les outils de génération effectuent des remplacements après la compilation. Ces remplacements modifient 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 affecté. Ils peuvent 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

L’intégration du Kit de développement logiciel (SDK) d’application Intune repose en grande partie sur les remplacements de classes et de méthodes. En raison de cette dépendance, vous voyez 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. Par exemple, MAMActivity fonctionne identique à Activity et onMAMCreate fonctionne identique à onCreate. Chaque fois que vous voyez mam dans une pile, commencez par 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 générez votre application avec aucun des outils précédents, 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.

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.

Matrice de compatibilité

Le plug-in de build du SDK MAM s’aligne sur les exigences de build Android et les tables de compatibilité. Les versions non répertoriées ici peuvent ou non fonctionner.

Exclusions

D’autres configurations 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 (autrement dit, 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 n’interfacent pas avec les bibliothèques Android ou les API système. Elles sont également utiles pour les projets qui 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, évitez ces exclusions.
• 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. 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 de debug build et release avec des saveurs {noMAM, MAM} et {mock, } , productionvous pouvez spécifier :
  • 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 d’autres vérifications pour rechercher d’éventuelles erreurs 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 pris par 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 changent. 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.

Le plug-in Gradle présente des limitations techniques dans les API qu’il utilise. En raison de ces limitations, les classes d’application doivent être retraitées lors de la transformation des classes de module de fonctionnalités dynamiques. Pour vous assurer que ce retraitement peut être effectué, configurez tous les modules de fonctionnalité avec les mêmes paramètres que l’application.

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 que le package NuGet Intune App SDK pour .NET MAUI - Android est 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 le plug-in Gradle et les cibles .NET détaillées ci-dessus. Toutefois, l’outil en ligne de commande peut être intégré à des systèmes de génération personnalisés. Étant donné que l’outil est plus générique, il est plus complexe à appeler. Utilisez le plug-in Gradle ou les cibles .NET 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 , le plug-in de android.app.Applicationbuild ou l’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 provoque 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 la stratégie sous-jacente dans Service.onBind et peuvent entraîner ServiceConnection.onNullBinding ou ServiceConnection.onServiceDisconnected. L’interaction avec un service lié établi peut générer un SecurityException en raison de l’application de la stratégie dans Binder.onTransact.

Les clients des services liés sont encouragés à case activée pour les exceptions levées par le service. Ne laissez pas les exceptions se propager au reste de l’application cliente.

Critères de sortie

Après avoir configuré le plug-in de build ou intégré l’outil en ligne de commande à 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 produisent 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. 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) Intune App n’incluaient aucun moyen automatisé d’effectuer des remplacements de classes et de méthodes. Les développeurs devaient effectuer ces remplacements manuellement dans le code source. Si votre application est 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. Vous n’avez pas besoin de modifier le 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.