Intune App SDK para Android: Introducción a MAM

El SDK de aplicaciones de Microsoft Intune para Android le permite incorporar Intune directivas de protección de aplicaciones en la aplicación nativa de Java/Kotlin para Android. Estas directivas también se conocen como directivas MAM. Una aplicación administrada por Intune es una que se integra con el SDK de Intune App. 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.

Fase 3: Introducción con MAM

Objetivos 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 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.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: esta Archivo de Android (AAR) contiene códigos auxiliares para las clases del sistema Android que solo están presentes en dispositivos más recientes, pero a los que se hace referencia mediante 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. 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 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

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 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 incluyó . 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. Debe completar estas integraciones antes de que la aplicación esté totalmente Intune habilitada. Revise detenidamente el resto de esta documentación para ver los puntos de integración pertinentes para la aplicación.

Depuración

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

MAM en la pila

La integración Intune App SDK se basa en gran medida en los reemplazos de clases y métodos. Debido a esta dependencia, 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. Por ejemplo, MAMActivity funciona idéntico a Activity y onMAMCreate funciona idéntico a onCreate. Siempre que vea mam en una pila, compruebe primero lo siguiente:

• ¿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 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 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.

Dependencias

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 agrega código javassist a la aplicación.

Matriz de compatibilidad

El complemento de compilación del SDK de MAM se alinea con los requisitos de compilación de Android y las tablas de compatibilidad. Es posible que las versiones que no se enumeran aquí funcionen o no.

Exclusiones

Se pueden proporcionar más configuraciones 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 controlar ni mostrar 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. 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 de Android o API del sistema, evite 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. 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:
  • noMAM para excluir todas las variantes con el sabor noMAM o
  • noMAMMockDebug para excluir solo esa variante exacta.

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

intunemam {
    report = true
}

Verificación

El complemento de compilación puede ejecutar más comprobaciones 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 podría 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 cambian. 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.

El complemento Gradle tiene limitaciones técnicas en las API que usa. Debido a estas limitaciones, 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 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 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 importan automáticamente en la aplicación en tiempo de compilación una vez que se agrega 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 el complemento 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 complejo invocar. Use el complemento 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 mediante los scripts auxiliares proporcionados ubicados en el BuildTool\bin directorio.

La herramienta espera los parámetros siguientes.

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.

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

Configuración de MAMApplication

Si la aplicación crea una subclase de , el complemento de android.app.Applicationcompilación o la herramienta de línea de comandos transforma 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 la aplicación de Intune sigue manteniendo el contrato proporcionado por la API de Android. Sin embargo, es posible que las condiciones de error se desencadenen con más frecuencia como resultado de la aplicación de directivas. Estos procedimientos recomendados de Android reducen 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, el uso Activity.startActivityForResult sin comprobar las requestCode causas de 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 a los clientes de servicios enlazados que comprueben si el servicio produce excepciones. 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 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 producen 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 Microsoft Entra que no tenga como destino la directiva de Protección de aplicaciones. Confirme 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 Intune App no incluyen ninguna forma 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 fase 4: Mam Integration Essentials.