Compartir a través de

Intune App SDK para Android: introducción a MAM

  • Artículo

El SDK de aplicaciones de Microsoft Intune para Android le permite incorporar Intune directivas de protección de aplicaciones (también conocidas como directivas de APLICACIÓN o MAM) en su aplicación nativa de Java/Kotlin Para Android. Una aplicación administrada por Intune es una que se integra con el SDK de Intune App. Intune los administradores pueden implementar fácilmente directivas de protección de aplicaciones en la aplicación administrada por Intune cuando Intune administra activamente la aplicación.

Nota:

Esta guía se divide en varias fases distintas. Para empezar, revise La fase 1: Planear la integración.

Fase 3: Introducción con MAM

Goals de fase

  • Descargue el SDK de Intune App.
  • Obtenga información sobre los archivos que se incluyen en el SDK de la aplicación de Intune.
  • Haga referencia al SDK de Intune App en la aplicación.
  • Configure el complemento de compilación Intune App Gradle o use la herramienta de compilación de la línea de comandos.
  • Confirme que el SDK de la aplicación de Intune está correctamente incluido en la compilación.

Información previa

Ahora que la aplicación ha integrado correctamente MSAL, es el momento de descargar el SDK de Intune App e incluirlo en el proceso de compilación de la aplicación.

Una gran parte de la integración del SDK de aplicaciones de Intune reemplaza las llamadas de método y las clases estándar de Android por Intune versiones de esas clases y llamadas de método. El SDK incluye herramientas de compilación que aprovechan automáticamente la mayoría de estos reemplazos. Si desea obtener más información sobre esta lógica de reemplazo, consulte la sección reemplazos de clases y métodos del apéndice.

Descarga del SDK de Intune App

Para descargar el SDK, consulte Descarga de los archivos del SDK.

¿Qué hay en el SDK?

El SDK de Intune App consta de los siguientes archivos:

  • Microsoft. Intune. MAM. SDK.aar: los componentes del SDK, excepto los archivos JAR de la biblioteca de soporte técnico.
  • com.microsoft.intune.mam.build.jar: complemento Gradle, que ayuda a integrar el SDK.
  • CHANGELOG.md: proporciona un registro de los cambios realizados en cada versión del SDK.
  • THIRDPARTYNOTICES.TXT: un aviso de atribución que reconoce código de terceros o del sistema operativo que se compilará en la aplicación.
  • Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: este AAR contiene códigos auxiliares para clases de sistema Android que solo están presentes en dispositivos más recientes, pero a los que hacen referencia los métodos de MAMActivity. Los dispositivos más recientes omiten estas clases de código auxiliar. Este AAR solo es necesario si la aplicación realiza una reflexión sobre las clases derivadas de MAMActivityy la mayoría de las aplicaciones no necesitan incluirla. AAR contiene reglas de ProGuard para excluir todas sus clases.

Hacer referencia a bibliotecas de aplicaciones de Intune

El SDK de Intune App es una biblioteca estándar de Android sin dependencias externas. Microsoft. Intune. MAM. SDK.aar contiene las interfaces necesarias para habilitar las directivas de protección de aplicaciones y el código necesario para interoperar con la aplicación Microsoft Intune Portal de empresa.

Android Studio

Microsoft. Intune. MAM. SDK.aar debe especificarse como referencia de biblioteca de Android. Para agregar esta dependencia a la compilación, siga Agregar AAR o JAR como dependencia de la documentación de Android.

Visual Studio

El paquete NuGet Intune App SDK para .NET MAUI - Android debe agregarse como una dependencia.

Siga el proceso de Instalación y administración de paquetes en Visual Studio mediante el Administrador de paquetes NuGet.

Microsoft.Intune. MAM. SDK.aar está enlazado para crear referencias de C# que tienen como ámbito el Microsoft.Intune.Mam espacio de nombres.

ProGuard

La aplicación ya puede usar ProGuard (o cualquier otro mecanismo de reducción o ofuscación) como paso de compilación. El SDK de Intune App tiene reglas de configuración de ProGuard que deben incluirse en ese paso de compilación. Incluir . AAR en la compilación, como se describió anteriormente, integra automáticamente la configuración del SDK en el paso ProGuard, por lo que se conservan los archivos de clase necesarios. Si ha incluido correctamente . AAR, no se necesita ningún otro cambio.

La Biblioteca de autenticación de Microsoft (MSAL) se incluye con su propia configuración de ProGuard. Si la aplicación integra MSAL, consulte la documentación de MSAL para obtener más detalles.

Creación de herramientas

El SDK proporciona herramientas de compilación (un complemento para compilaciones de Gradle, destinos para compilaciones de .NET y una herramienta de línea de comandos) que realizan reemplazos de MAM automáticamente. Estas herramientas transforman los archivos de clase generados por la compilación de Java; no modifican el código fuente original. Debe usar el complemento Gradle, el paquete NuGet de .NET o la herramienta de línea de comandos.

Las herramientas de compilación por sí solas no son suficientes para integrar completamente la aplicación. Las herramientas solo realizan reemplazos de clases y métodos. No realizan integraciones de SDK más complejas, como Multi-Identity, Registering for App Protection Policy, Policy for limiting data transfer between apps and device or cloud storage locations, or MSAL configuration, which must be completed before your app is fully Intune enabled. Revise detenidamente el resto de esta documentación para ver los puntos de integración pertinentes para la aplicación.

Impacto en la depuración

Las herramientas de compilación realizan reemplazos después de la compilación, lo que cambiará algunos nombres de método. Como resultado, es posible que los puntos de interrupción de depuración establecidos en los nombres de método se vean afectados y no se detengan según lo esperado. Los puntos de interrupción de número de línea no se ven afectados.

MAM en la pila

Dado que la integración Intune App SDK se basa en gran medida en los reemplazos de clases y métodos, comenzará a ver mam a lo largo de los seguimientos de la pila. Cuando la aplicación no tiene una cuenta destinada a directivas de protección de aplicaciones, todo este código MAM permanece inactivo: MAMActivity funcionará idéntico a , onMAMCreate funcionará idéntico a ActivityonCreate, etc. Siempre que vea mam en una pila, compruebe primero:

  • ¿La cuenta está destinada a directivas de protección de aplicaciones?
  • ¿Está instalado el Portal de empresa de Intune?

A menos que la respuesta a ambos sea "sí", el código MAM actúa como paso a través simple.

¿Qué herramienta necesito?

Si compila la aplicación con Gradle, consulte Integración con el complemento de compilación de Gradle.

Si compila la aplicación con .NET MAUI, consulte Integración con los destinos de .NET MAUI.

Si compilas la aplicación con ninguna de las anteriores, consulta Integración con la herramienta de línea de comandos.

Integración con el complemento de compilación gradle

El complemento Intune App SDK se distribuye como parte del SDK como GradlePlugin/com.microsoft.intune.mam.build.jar.

Para que Gradle reconozca el complemento, debe agregarse a la ruta de buildscript clase. El complemento depende de Javassist, que también debe agregarse. Para obtener más información sobre la dependencia de Javassist, consulte Dependencias.

Para agregarlos a la ruta de acceso de clase, agregue lo siguiente a la raíz 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")
    }
}

A continuación, para aplicar el complemento, agregue lo siguiente al archivo para la build.gradle aplicación y los módulos de características dinámicas:

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

De forma predeterminada, el complemento funciona en project dependencias y bibliotecas externas. La compilación de pruebas no se ve afectada.

Nota:

A partir de la versión 8.0 Intune App SDK, ya no es posible procesar bibliotecas de forma selectiva. Se procesan todas las bibliotecas.

Dependencias

Nota:

Debe usar la versión 3.6.1 o posterior del complemento Android Gradle y la versión 5.6.4 o posterior de Gradle.

El complemento Gradle tiene una dependencia en Javassist, que debe estar disponible para la resolución de dependencias de Gradle. Javassist se usa únicamente en tiempo de compilación al ejecutar el complemento y no se agregará código javassist a la aplicación.

Nota:

Es posible que las versiones de Javassist no sean compatibles con versiones anteriores. Por lo general, debe usar la versión exacta esperada por el SDK de Intune App:

  • Intune SDK de aplicaciones ≥ 10.0.0 requiere Javassist 3.29.2-GA
  • Intune SDK de aplicaciones ≥ 7.0.0 requiere Javassist 3.27.0-GA
  • Intune APP SDK < 7.0.0 requiere Javassist 3.22.0-GA

Además, al consumir MAM SDK 8.0.0+, debe asegurarse de que se establece lo siguiente en la configuración de Gradle:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Exclusiones

Se pueden proporcionar configuraciones adicionales para excluir componentes específicos de la aplicación de reescrituras. Las exclusiones son predominantemente útiles para los componentes que no son relevantes para MAM (es decir, no controlan ni muestran datos corporativos).

Las exclusiones se pueden configurar para distintos ámbitos:

  • excludeProjects permite excluir una lista de proyectos de Gradle. Estas exclusiones son útiles para proyectos que no interactúan con bibliotecas de Android o API del sistema o que no controlan datos corporativos. Por ejemplo, un proyecto que contenga exclusivamente código nativo para realizar operaciones de red de bajo nivel podría ser un buen candidato. Si un proyecto interactúa ampliamente con bibliotecas de Android o API del sistema, se deben evitar estas exclusiones.
  • excludeClasses permite excluir una lista de clases. Estas exclusiones son útiles para las clases que no controlan ni presentan datos corporativos. Por ejemplo, las pantallas de presentación y las de incorporación Activityson buenos candidatos. Tenga en cuenta que no se puede excluir una clase si se procesa cualquiera de sus superclases.
  • excludeVariants permite excluir variantes de proyecto. Estas exclusiones pueden hacer referencia a un nombre de variante completo o a un único tipo. Son especialmente útiles si quieres crear un tipo de aplicación que no sea MAM. Por ejemplo, si la aplicación tiene tipos debug de compilación y release con los tipos {noMAM, MAM} y {mock, production} puede especificar lo siguiente:
    • noMAM para excluir todas las variantes con el sabor noMAM o
    • noMAMMockDebug para excluir solo esa variante exacta.

Precaución

Las exclusiones no deben tomarse a la ligera. La aplicación incorrecta de exclusiones puede dar lugar a pérdidas de datos graves en la aplicación. Valide siempre el impacto de cualquier exclusión que aplique.

Ejemplo de build.gradle parcial con exclusiones

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

Esto tendría los siguientes efectos:

  • :product:FooLib no se reescribió porque está incluido en excludeProjects
  • :product:foo-project se vuelve a escribir, excepto para com.contoso.SplashActivity, que se omite porque está en excludeClasses
  • com.microsoft.bar:baz.1.0.0 se vuelve a escribir porque todas las bibliotecas externas se incluyen para su procesamiento.
  • Las variantes con el noMAM sabor no se vuelven a escribir.

Reporting

El complemento de compilación puede generar un informe html de los cambios que realiza. Para solicitar la generación de este informe, especifique report = true en el bloque de intunemam configuración. Si se genera, el informe se escribirá outputs/logs en en el directorio de compilación.

intunemam {
    report = true
}

Verificación

El complemento de compilación puede ejecutar una comprobación adicional para buscar posibles errores en el procesamiento de clases. Estas comprobaciones ayudan a protegerse frente a posibles errores en tiempo de ejecución inducidos por complementos.

Para solicitar que se realice la comprobación en la compilación, especifique verify = true en el bloque de intunemam configuración. Esto puede agregar varios segundos al tiempo que tarda la tarea del complemento.

intunemam {
    verify = true
}

Por lo general, un error de comprobación representa un error en el complemento de compilación. Para obtener ayuda con un error, escale el problema con el soporte técnico de Microsoft. Si no tiene un contrato de soporte técnico de Microsoft, abra un problema de GitHub.

Compilaciones incrementales

Para habilitar la compatibilidad con la compilación incremental, especifique incremental = true en el bloque de intunemam configuración. Esta característica aumenta el rendimiento de la compilación procesando solo los archivos de entrada que han cambiado. La configuración predeterminada para incremental es false.

intunemam {
    incremental = true
}

Configuración del módulo de características dinámicas

Los módulos de características dinámicas se compilan por separado del proyecto de aplicación. Por lo tanto, los módulos de características dinámicas también deben aplicar el complemento de compilación gradle.

Debido a las limitaciones técnicas de las API usadas por el complemento Gradle, las clases de aplicación deben volver a procesarse al transformar las clases de módulo de características dinámicas. Para asegurarse de que esto se puede hacer, todos los módulos de características deben configurarse con la misma configuración que la aplicación para la que está diseñada.

Por ejemplo, si una aplicación excluye una clase, el módulo de características dinámicas también debe excluir esa clase.

Integración con los destinos de MAUI de .NET

Los destinos del SDK de Intune App se distribuyen como parte del SDK como Microsoft.Intune. Maui. Essentials.android.targets.

Los destinos se importarán automáticamente en la aplicación en tiempo de compilación una vez que se agregue el paquete NuGet Intune App SDK para .NET MAUI - Android.

Integración con la herramienta de compilación de línea de comandos

La herramienta de compilación de la línea de comandos está disponible en la BuildTool carpeta de la colocación del SDK. Realiza la misma función que los destinos del complemento Gradle/.NET detallados anteriormente, pero se puede integrar en sistemas de compilación personalizados. Como es más genérico, es más complejo invocar, por lo que el complemento Gradle o los destinos de .NET se deben usar siempre que sea posible.

Uso de la herramienta Command-Line

La herramienta de línea de comandos se puede invocar mediante los scripts auxiliares proporcionados ubicados en el BuildTool\bin directorio.

La herramienta espera los parámetros siguientes.

Parámetro Obligatorio Descripción
--input Sí Lista delimitada por puntos y coma de archivos jar y directorios de archivos de clase que se van a modificar. Esto debe incluir todos los archivos jar o directorios que tiene previsto reescribir.
--output Yes Una lista delimitada por puntos y coma de archivos jar y directorios en los que almacenar las clases modificadas. Debe haber una entrada de salida por entrada de entrada y deben aparecer en orden.
--classpath Yes Ruta de clase de compilación. Puede contener archivos JAR y directorios de clases.
--processed No Lista delimitada por puntos y coma de archivos jar y directorios que contienen clases que ya se han procesado mediante una invocación anterior de la herramienta de compilación.
--excludeClasses No Lista delimitada por puntos y comas que contiene los nombres de las clases que se deben excluir de la reescritura.
--report No Directorio en el que se va a escribir un informe HTML sobre las clases modificadas. Si no se especifica, no se escribe ningún informe.

La opción opcional --processed se usa para habilitar compilaciones incrementales. El conjunto de archivos o directorios enumerados aquí debe estar separado de las listas de entrada y ruta de clase.

Sugerencia

En sistemas similares a Unix, los puntos y comas son separadores de comandos. Para evitar que el shell divida comandos, asegúrese de escapar cada punto y coma con "" o encapsular el parámetro completo entre comillas.

Invocación de la herramienta de Command-Line de ejemplo

> 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

Esto tendría los siguientes efectos:

  • el product-foo-project directorio se vuelve a escribir en mam-build\product-foo-project
  • bar.jar se vuelve a escribir en mam-build\libs\bar.jar
  • zap.jar no se reescribió porque solo aparece en--classpath
  • La com.contoso.SplashActivity clase no se vuelve a escribir aunque esté en --input

Advertencia

La herramienta de compilación no admite actualmente archivos aar. Si el sistema de compilación aún no extrae classes.jar al tratar con archivos aar, tendrá que hacerlo antes de invocar la herramienta de compilación.

Configuración de MAMApplication

Si la aplicación crea una subclase de , la herramienta de línea de android.app.Applicationcomandos o complemento de compilación transformará la clase de aplicación.

Si la aplicación no tiene subclase android.app.Application, debe establecer "com.microsoft.intune.mam.client.app.MAMApplication" como atributo en la "android:name" etiqueta del <application> AndroidManifest.xml.

  • Use las herramientas de compilación de Android SDK más recientes.
  • Quite todas las bibliotecas innecesarias y no utilizadas (por ejemplo, android.support.v4).

Después de realizar reemplazos automáticos, el SDK de la aplicación de Intune sigue manteniendo el contrato proporcionado por la API de Android. Sin embargo, las condiciones de error se pueden desencadenar con más frecuencia como resultado de la aplicación de directivas. Estos procedimientos recomendados de Android reducirán la probabilidad de error:

  • Las funciones del SDK de Android que pueden devolver null ahora tienen una mayor probabilidad de devolver null. Asegúrese de que null las comprobaciones protegen estas llamadas de función.
  • Las características que se pueden comprobar, como clipboardManager.getPrimaryClipDescription(), se deben comprobar a través de sus API de reemplazo de MAM, como MAMClipboard.getPrimaryClipDescription(clipboardManager).
  • Todas las funciones derivadas deben llamar a través de sus versiones de superclase.
  • Evite el uso de cualquier API de forma ambigua. Por ejemplo, si se usa Activity.startActivityForResult sin comprobar, requestCode se producirá un comportamiento extraño.

Servicios

La aplicación de directivas puede afectar a las interacciones del servicio Android. Los métodos que establecen una conexión de servicio enlazada, como Context.bindService , pueden producir un error debido a la aplicación de directivas subyacente en Service.onBind y pueden dar lugar ServiceConnection.onNullBinding a o ServiceConnection.onServiceDisconnected. La interacción con un servicio enlazado establecido puede producir un SecurityException debido a la aplicación de directivas en Binder.onTransact.

Se recomienda encarecidamente a los clientes de servicios enlazados que comprueben si el servicio produce excepciones en lugar de permitir que las excepciones se propaguen al resto de la aplicación cliente.

Criterios de salida

Después de configurar el complemento de compilación o de integrar la herramienta de línea de comandos en el proceso de compilación, compruebe que se ejecuta correctamente:

  • Asegúrese de que la compilación se compila y compila correctamente.
  • Configure la report marca y, a continuación, abra el documento de informe y confirme que se están produciendo reemplazos de clases y métodos:
    • Si usa el complemento, siga los pasos descritos en Informes.
    • Si usa la herramienta de línea de comandos, incluya la --report marca .
  • Si usa el complemento, configure la verify marca y asegúrese de que no produce errores. Consulte Verificación.
  • Compruebe todas las exclusiones (excludeProjects, excludeClassesy excludeVariants) en build.gradle. Confirme que cada exclusión es necesaria y no trata con datos protegidos. Históricamente se han producido muchos errores de pérdida de datos debido a exclusiones excesivamente agresivas.
  • Sin la Portal de empresa de Intune instalada, inicie la aplicación compilada, inicie sesión con un usuario de Microsoft Entra que no tenga como destino la directiva de Protección de aplicaciones y confirme que la aplicación funciona según lo previsto.
    • Cierre la sesión y repita esta prueba con el Portal de empresa de Intune instalado.

Preguntas más frecuentes

Mi aplicación integró previamente el SDK sin el complemento de compilación; ¿cómo puedo usar el complemento de compilación?

Las versiones anteriores del SDK de Intune App no incluyeban ninguna forma automatizada de realizar reemplazos de clases y métodos, y los desarrolladores necesitaban realizar estos reemplazos manualmente en el código fuente. Si la aplicación se había integrado previamente de esta manera, es seguro aplicar el complemento de compilación (o la herramienta de compilación de línea de comandos) sin modificaciones en el código fuente. El proyecto debe seguir enumerando el SDK de MAM como una dependencia.

Pasos siguientes

Después de completar todos los criterios de salida, continúe con la fase 4: Integración mam Essentials.