SDK de la aplicación de Intune para Android: introducción a MAM

El SDK de aplicaciones de Microsoft Intune para Android le permite incorporar directivas de protección de aplicaciones de Intune en su aplicación nativa de Android Java/Kotlin. Estas directivas también se conocen como directivas MAM. Una aplicación administrada por Intune es aquella que está integrada con el SDK de la aplicación de Intune. Cuando Intune administra activamente la aplicación, los administradores de Intune pueden implementar fácilmente directivas de protección de aplicaciones en la aplicación administrada por Intune.

Nota:

Esta guía se divide en varias etapas distintas. Comience por revisar la Etapa 1: Planifique la integración.

Fase 3: Introducción a MAM

Objetivos de la etapa

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

Información previa

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

Una gran parte de la integración del SDK de la aplicación de Intune es reemplazar las clases estándar de Android y las llamadas a métodos por versiones de Intune de esas clases y llamadas a métodos. El SDK incluye herramientas de compilación que realizan 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 clase y método del apéndice.

Descargar el SDK de la aplicación de Intune

Para descargar el SDK, consulte Descargar los archivos SDK.

¿Qué hay en el SDK?

El SDK de la aplicación de Intune consta de los siguientes archivos:

  • Microsoft. Intune. MAM. SDK.aar: Los componentes del SDK, excepto los archivos JAR de la biblioteca de soporte.
  • com.microsoft.intune.mam.build.jar: Un complemento de Gradle, que ayuda a integrar el SDK.
  • CHANGELOG.md: Proporciona un registro de los cambios realizados en cada versión del SDK.
  • Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: este archivo de Android (AAR) contiene códigos auxiliares para las clases del sistema Android que están presentes solo en dispositivos más nuevos, pero a las que se hace referencia mediante métodos en MAMActivity. Los dispositivos más nuevos ignoran estas clases de código auxiliar. Este AAR solo es necesario si la aplicación realiza una reflexión sobre las clases derivadas de MAMActivity, y la mayoría de las aplicaciones no necesitan incluirlo. El AAR contiene reglas ProGuard para excluir todas sus clases.

Hacer referencia a las bibliotecas de aplicaciones de Intune

El SDK de la aplicación de Intune es una biblioteca Android estándar sin dependencias externas. Microsoft. Intune. MAM. SDK.aar contiene las interfaces necesarias para habilitar las directivas de protección de aplicaciones. También contiene 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 a la biblioteca de Android. Para agregar esta dependencia a la compilación, siga Agregar el AAR o JAR como dependencia de la documentación de Android.

Visual Studio

El SDK de la aplicación de Intune para .NET MAUI: el paquete NuGet de 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.

El archivo Microsoft.Intune. MAM. SDK.aar está destinado a crear referencias de C# que están sujetas al espacio de Microsoft.Intune.Mam nombres.

ProGuard

Es posible que la aplicación ya use ProGuard (o cualquier otro mecanismo de reducción o ofuscación) como paso de compilación. El SDK de la aplicación de Intune tiene reglas de configuración de ProGuard que deben incluirse en ese paso de compilación. Incluido el archivo . AAR en su 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 incluiste el archivo . AAR, no se necesita ningún otro cambio.

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

Herramientas de compilación

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 automáticamente reemplazos de MAM. Estas herramientas transforman los archivos de clase generados por la compilación Java; No modifican el código fuente original. Debe usar el complemento de 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 identidad múltiple, registro para la directiva de protección de aplicaciones, directiva para limitar la transferencia de datos entre aplicaciones y dispositivos o ubicaciones de almacenamiento en la nube, o la configuración de MSAL. Debes completar estas integraciones antes de que la aplicación esté totalmente habilitada para Intune. Revise detenidamente el resto de esta documentación para ver los puntos de integración relevantes para su aplicación.

Depuración

Las herramientas de compilación realizan reemplazos después de la compilación. Estos reemplazos cambian algunos nombres de métodos. Como resultado, la depuración de puntos de interrupción establecidos en nombres de método podría verse afectada. Es posible que no se detengan como se esperaba. Los puntos de interrupción del número de línea no se ven afectados.

MAM en la pila

La integración del SDK de la aplicación de Intune depende en gran medida de los reemplazos de clases y métodos. Debido a esta dependencia, verá mam a través de los seguimientos de la pila. Cuando la aplicación no tiene una cuenta destinada con directivas de protección de aplicaciones, todo este código MAM permanece inactivo. Por ejemplo, MAMActivity funciona idéntico a Activity y onMAMCreate funciona idéntico a onCreate. Siempre que vea mam en una pila, compruebe primero:

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

A menos que la respuesta a ambas opciones sea "sí", el código MAM actúa como un simple paso.

¿Qué herramienta necesito?

Si compilas tu aplicación con Gradle, consulta Integración con el complemento de compilación de Gradle

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

Si compila la aplicación con ninguna de las herramientas anteriores, consulte Integración con la herramienta de línea de comandos.

Integración con el complemento de compilación de Gradle

El complemento SDK de Intune App 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 classpath, agregue lo siguiente a su 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, agrega lo siguiente al archivo para la aplicación y los build.gradle módulos de funciones 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 del SDK de aplicaciones de Intune 8.0, ya no es posible procesar bibliotecas de forma selectiva. Se procesan todas las bibliotecas.

Dependencias

El complemento de Gradle tiene una dependencia de Javassist, que debe estar disponible para la resolución de dependencias de Gradle. Javassist se usa únicamente en tiempo de compilación cuando se ejecuta el complemento y no se agrega código Javassist a su aplicación.

MAM SDK Versión de Javassist
≥ 10.0.0 3.29.2-GA
≥ 7.0.0 3.27.0-GA
< 7.0.0 3.22.0-GA

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 aplicación de Intune.

Matriz de compatibilidad

El complemento de compilación del SDK de MAM se ajusta a los requisitos de compilación y a las tablas de compatibilidad de Android. Las versiones que no aparecen en esta lista podrían funcionar o no.

MAM SDK Versión de Android Gradle Complemento de Android Gradle Versión de Kotlin Versión de Java
10.0.0 14 8.2 8. 2. 2 1.9.25 17
11.0.0 15 8.7 8.6.1 2.0.21 17
12.0.0 16 8.11.1 8.9.1 2.1.21 17

Exclusiones

Se pueden proporcionar más configuraciones para excluir componentes específicos de la aplicación de las reescrituras. Las exclusiones son útiles principalmente 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 Android o API del sistema. También son útiles para proyectos 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 o API del sistema de Android, evita estas exclusiones.
  • excludeClasses Permite excluir una lista de clases. Estas exclusiones son útiles para las clases que no manejan ni presentan datos corporativos. Por ejemplo, las pantallas de presentación y las incorporaciones Activityson buenos candidatos. Una clase no se puede excluir si se procesa alguna de sus superclases.
  • excludeVariants Habilita la exclusión de variantes de proyecto. Estas exclusiones pueden hacer referencia a un nombre de variante completo o a un solo sabor. Son especialmente útiles si desea crear una versión de su aplicación que no sea de MAM. Por ejemplo, si tu aplicación tiene tipos debug de compilación y release con sabores {noMAM, MAM} y {mock, production}, podrías especificar lo siguiente:
    • noMAM excluir todas las variantes con la variante noMAM o
    • noMAMMockDebug excluir solo esa variante exacta.

Precaución

Las exclusiones no deben tomarse a la ligera. La aplicación incorrecta de exclusiones puede provocar graves pérdidas de datos en la aplicación. Valide siempre el efecto 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 ha reescrito porque se incluye en excludeProjects
  • :product:foo-project se reescribe, excepto para , que com.contoso.SplashActivityse omite porque está en excludeClasses
  • com.microsoft.bar:baz.1.0.0 se ha reescrito porque se incluyen todas las bibliotecas externas para el procesamiento.
  • Las variantes con el noMAM sabor no se reescriben.

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 escribe outputs/logs en el directorio de compilación.

intunemam {
    report = true
}

Comprobación

El complemento de compilación puede ejecutar más verificaciones para buscar posibles errores en las clases de procesamiento. Estas comprobaciones ayudan a protegerse contra posibles fallos en tiempo de ejecución inducidos por el plugin.

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

intunemam {
    verify = true
}

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

Compilaciones incrementales

Para permitir 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 al procesar solo los archivos de entrada que cambian. La configuración predeterminada es incrementalfalse.

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 la aplicación. Como tal, los módulos de funciones dinámicas también deben aplicar el complemento de compilación de Gradle.

El complemento de Gradle tiene limitaciones técnicas en las API que usa. Debido a estas limitaciones, las clases de aplicaciones deben volver a procesarse al transformar clases de módulos de entidades dinámicas. Para asegurarse de que se puede realizar este reprocesamiento, configure todos los módulos de características con la misma configuración que la aplicación.

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 MAUI de .NET

Los destinos del SDK de la aplicación de Intune se distribuyen como parte del SDK como Microsoft.Intune. Maui.Essentials.android.targets.

Los destinos se importan automáticamente en la aplicación en tiempo de compilación una vez que se agrega el SDK de la aplicación de Intune para .NET MAUI: paquete NuGet de Android.

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

La herramienta de compilación de línea de comandos está disponible en la BuildTool carpeta de SDK drop. Realiza la misma función que el complemento de Gradle y los destinos de .NET detallados anteriormente. Sin embargo, la herramienta de línea de comandos se puede integrar en sistemas de compilación personalizados. Dado que la herramienta es más genérica, es más compleja de invocar. Use el complemento de Gradle o los destinos de .NET siempre que sea posible.

Uso de la herramienta Command-Line

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

La herramienta espera los siguientes parámetros.

Parámetro Obligatorio Descripción
--input Sí Una lista delimitada por puntos y coma de archivos JAR y directorios de archivos de clase para modificar. Incluya todos los JAR y directorios que pretende reescribir.
--output Sí Una lista delimitada por puntos y coma de archivos y directorios JAR para almacenar las clases modificadas. Proporcione una entrada de salida por cada entrada de entrada, enumerada en el mismo orden.
--classpath Sí La ruta de clase de compilación. Puede contener tanto archivos JAR como directorios de clases.
--processed No Una lista delimitada por puntos y coma de archivos y directorios JAR que contienen clases que ya han sido procesadas por una invocación previa de la herramienta de compilación.
--excludeClasses No Una lista delimitada por puntos y comas que contiene los nombres de las clases que se deben excluir de la reescritura.
--report No Directorio para 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/directorios enumerados aquí debe estar separado de las listas input y classpath.

Sugerencia

En sistemas similares a Unix, el punto y coma es un separador de comandos. Para evitar que el shell divida los comandos, asegúrese de escapar cada punto y coma con '' o ajustar el parámetro completo entre comillas.

Ejemplo Command-Line invocación de herramientas

> 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 reescribe en mam-build\product-foo-project
  • bar.jar se ha reescrito en mam-build\libs\bar.jar
  • zap.jar no se ha reescrito porque solo aparece en--classpath
  • La com.contoso.SplashActivity clase no se reescribe, incluso si está dentro --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, extráigalo antes de invocar la herramienta de compilación.

Configuración de MAMApplication

Si tu app crea una subclase de , entonces el plugin de compilación o la herramienta de línea de comandos transforma tu clase de android.app.Applicationaplicación.

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

  • Usa las herramientas de compilación del SDK de Android más recientes.
  • Quitar todas las bibliotecas innecesarias y sin usar (por ejemplo, android.support.v4).

Después de realizar reemplazos automáticos, el SDK de aplicaciones de Intune sigue manteniendo el contrato proporcionado por la API de Android. Sin embargo, las condiciones de error podrían desencadenarse con más frecuencia como resultado de la aplicación de directivas. Estas prácticas recomendadas de Android reducen la probabilidad de errores:

  • Las funciones del SDK de Android que pueden devolverse 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(), deben comprobarse a través de sus API de reemplazo de MAM, como MAMClipboard.getPrimaryClipDescription(clipboardManager).
  • Todas las funciones derivadas deben llamar a sus versiones de superclase.
  • Evite el uso de cualquier API de forma ambigua. Por ejemplo, usar Activity.startActivityForResult sin verificar los requestCode provoca 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, por ejemplo Context.bindService , podrían producirse errores debido a la aplicación de directivas subyacentes en Service.onBind y podrían dar lugar ServiceConnection.onNullBinding a o ServiceConnection.onServiceDisconnected. La interacción con un servicio vinculado establecido puede producir un SecurityException debido a la aplicación de directivas en Binder.onTransact.

Se recomienda a los clientes de servicios enlazados que comprueben si hay excepciones lanzadas por el servicio. No permita 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 integrar la herramienta de línea de comandos en el proceso de compilación, valide que se ejecuta correctamente:

  • Asegúrese de que la compilación se compila y compila correctamente.
  • Configure la report marca, 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 bandera y asegúrese de que no produzca errores. Consulta Verificación.
  • Vuelva a marcar todas las exclusiones (excludeProjects, excludeClasses, y excludeVariants) en build.gradle. Confirme que cada exclusión es necesaria y no trata con datos protegidos. Históricamente, muchos errores de pérdida de datos ocurren debido a exclusiones demasiado agresivas.
  • Sin el Portal de empresa de Intune instalado, inicie la aplicación compilada. Inicie sesión con un usuario de Microsoft Entra que no esté de destino con la directiva de protección de aplicaciones. Confirma que la aplicación funciona según lo esperado.
    • 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 aplicaciones de Intune no incluían ninguna manera automatizada de realizar reemplazos de clases y métodos. Los desarrolladores necesitaban realizar estos reemplazos manualmente en el código fuente. Si la aplicación está integrada de esta manera, es seguro aplicar el complemento de compilación o la herramienta de compilación de línea de comandos. No necesita ninguna modificación del 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 Etapa 4: Fundamentos de integración de MAM.

  • Last updated on