SDK de aplicaciones de Intune para Android: introducción a MAM

El SDK de aplicaciones Microsoft Intune para Android le permite incorporar directivas de protección de aplicaciones de Intune (también conocidas como directivas de APLICACIÓN o MAM) en la aplicación nativa de Java/Kotlin para Android. Una aplicación administrada por Intune es una que se integra con el SDK de aplicaciones de Intune. Los administradores de Intune 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 aplicaciones de Intune.
• Obtenga información sobre los archivos que se incluyen en el SDK de aplicaciones de Intune.
• Haga referencia al SDK de aplicaciones de Intune en la aplicación.
• Configure el complemento de compilación gradle de aplicaciones de Intune o use la herramienta de compilación de línea de comandos.
• Confirme que el SDK de aplicaciones de Intune se incluye 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 aplicaciones de Intune 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 consiste en reemplazar las clases y las llamadas de método estándar de Android por versiones de Intune 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 aplicaciones de Intune

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

¿Qué hay en el SDK?

El SDK de aplicaciones 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 técnico.
• com.microsoft.intune.mam.build.jar: un 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 se hace referencia mediante métodos en 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.

Referencia a bibliotecas de aplicaciones de Intune

El SDK de aplicaciones de Intune 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 una referencia de biblioteca de Android:

1. Abra el proyecto de aplicación en Android Studio y vaya al módulo Nuevo > archivo nuevo>.
2. Seleccione Importar . TARRO/. Paquete AAR.
3. Seleccione Microsoft.Intune.MAM.SDK.aar para crear un módulo para . Tipo de archivo AAR .
4. Haga clic con el botón derecho en el módulo o módulos que contiene el código de la aplicación y vaya ala pestaña> Dependencias de configuración> del módulo + icono>Dependencia del módulo.
5. Seleccione el módulo AAR del SDK de MAM que creó y seleccione Aceptar. Agregar esta referencia garantiza que el módulo se compile con el SDK de MAM al compilar el proyecto.

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 aplicaciones de Intune 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 multiinquilino, registro de directivas de protección de aplicaciones, directiva para limitar la transferencia de datos entre aplicaciones y ubicaciones de almacenamiento en la nube o dispositivos, o la configuración de MSAL, que debe completarse 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 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 del SDK de aplicaciones de Intune se basa en gran medida en los reemplazos de clases y métodos, comenzará a ver mam 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 sdk de aplicaciones de Intune 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 build.gradle archivo del módulo de aplicación:

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

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 aplicaciones de Intune:

• El SDK de aplicaciones de Intune ≥ 10.0.0 requiere Javassist 3.29.2-GA
• El SDK de aplicaciones de Intune ≥ 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
}

Integración con los destinos de MAUI de .NET

Los destinos del SDK de aplicaciones de Intune 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	Sí	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	Sí	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.jarno 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.

Procedimientos recomendados de Android

• 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 aplicaciones 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 aplicaciones de Intune 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: MAM Integration Essentials.