Пакет SDK для приложений Intune для Android — начало работы с MAM

Пакет SDK для приложений Microsoft Intune для Android позволяет включить политики защиты приложений Intune (также известные как политики ПРИЛОЖЕНИЙ или MAM) в собственное приложение Java/Kotlin для Android. Приложение, управляемое Intune, интегрировано с пакетом SDK для приложений Intune. Администраторы Intune могут легко развертывать политики защиты приложений в приложении, управляемом Intune, когда Intune активно управляет приложением.

Примечание.

Это руководство разделено на несколько отдельных этапов. Начните с просмотра этапа 1. Планирование интеграции.

Этап 3. начало работы с MAM

Этап Goals

• Скачайте пакет SDK для приложений Intune.
• Узнайте, какие файлы включены в пакет SDK для приложений Intune.
• Ссылка на пакет SDK для приложений Intune в приложении.
• Настройте подключаемый модуль intune App Gradle Build или используйте средство сборки из командной строки.
• Убедитесь, что пакет SDK для приложений Intune правильно включен в сборку.

Общие сведения

Теперь, когда приложение успешно интегрировано в MSAL, пришло время скачать пакет SDK для приложений Intune и включить его в процесс сборки приложения.

Большая часть интеграции пакета SDK для приложений Intune заменяет стандартные классы Android и вызовы методов версиями Intune этих классов и вызовов методов. Пакет SDK включает средства сборки, которые автоматически делают большинство из этих замен. Если вы хотите узнать больше об этой логике замены, см. раздел замены классов и методовприложения.

Скачивание пакета SDK для приложений Intune

Сведения о том, как скачать пакет SDK, см . в разделе Скачивание файлов пакета SDK.

Что в пакете SDK?

Пакет SDK для приложений Intune состоит из следующих файлов:

• Microsoft.Intune.MAM.SDK.aar: компоненты пакета SDK, за исключением JAR-файлов библиотеки поддержки.
• com.microsoft.intune.mam.build.jar: подключаемый модуль Gradle, который помогает интегрировать пакет SDK.
• CHANGELOG.md. Предоставляет запись изменений, внесенных в каждую версию пакета SDK.
• THIRDPARTYNOTICES.TXT: уведомление об атрибутах, которое подтверждает сторонний код и (или) OSS, который будет компилироваться в приложение.
• Microsoft.Intune.MAM.SDK.DownlevelStubs.aar: этот AAR содержит заглушки для системных классов Android, которые присутствуют только на новых устройствах, но на которые ссылаются методы В MAMActivity. Новые устройства игнорируют эти классы заглушки. Этот AAR необходим только в том случае, если приложение выполняет рефлексию над классами, производными от MAMActivity, и большинство приложений не должны включать его. AAR содержит правила ProGuard, исключающие все его классы.

Ссылки на библиотеки приложений Intune

Пакет SDK для приложений Intune — это стандартная библиотека Android без внешних зависимостей. Microsoft.Intune.MAM.SDK.aar содержит интерфейсы, необходимые для включения политик защиты приложений, и код, необходимый для взаимодействия с приложением Microsoft Intune Корпоративный портал.

Android Studio

Microsoft.Intune.MAM.SDK.aar необходимо указать в качестве ссылки на библиотеку Android:

1. Откройте проект приложения в Android Studio и перейдите к файлу > Новый > модуль.
2. Выберите Импорт . БАНКУ/. Пакет AAR.
3. Выберите Microsoft.Intune.MAM.SDK.aar, чтобы создать модуль для . Тип файла AAR .
4. Щелкните правой кнопкой мыши модуль или модули, содержащие код приложения, и перейдите навкладку>Параметры> модуля Зависимости+ значок>Зависимость модуля.
5. Выберите созданный модуль AAR пакета SDK для MAM и нажмите кнопку ОК. Добавление этой ссылки гарантирует, что модуль будет компилироваться с помощью пакета SDK MAM при сборке проекта.

Visual Studio

Пакет SDK для приложений Intune для .NET MAUI — Android необходимо добавить в качестве зависимости.

Выполните процедуру установки пакетов и управления ими в Visual Studio с помощью диспетчера пакетов NuGet.

Microsoft.Intune.MAM.SDK.aar привязывается к созданию ссылок на C#, которые относятся к пространству Microsoft.Intune.Mam имен.

ProGuard

Приложение уже может использовать ProGuard (или любой другой механизм сжатия или маскировки) в качестве шага сборки. Пакет SDK для приложений Intune содержит правила конфигурации ProGuard, которые должны быть включены в этот шаг сборки. Включая . AAR в сборке, как описано выше, автоматически интегрирует конфигурацию пакета SDK в шаг ProGuard, чтобы сохранить необходимые файлы классов. Если вы правильно включили . AAR, никаких других изменений не требуется.

Библиотека проверки подлинности Майкрософт (MSAL) поставляется с собственной конфигурацией ProGuard. Если приложение интегрирует MSAL, дополнительные сведения см. в документации по MSAL .

Средства сборки

Пакет SDK предоставляет средства сборки (подключаемый модуль для сборок Gradle, целевые объекты для сборок .NET и средство командной строки), которые автоматически заменяют MAM. Эти средства преобразуют файлы классов, созданные компиляцией Java; они не изменяют исходный исходный код. Необходимо использовать подключаемый модуль Gradle, пакет NuGet для .NET или программу командной строки.

Одних средств сборки недостаточно для полной интеграции приложения. Средства выполняют только замену классов и методов . Они не выполняют более сложные интеграции с пакетом SDK, такие как использование нескольких удостоверений, регистрация для политики защиты приложений, политика ограничения передачи данных между приложениями и устройствами или облачными хранилищами, а также настройка MSAL, которая должна быть завершена, прежде чем приложение полностью включит Intune. Внимательно изучите остальную часть этой документации на наличие точек интеграции, относящихся к вашему приложению.

Влияние на отладку

Средства сборки выполняют замены после компиляции, что приведет к изменению некоторых имен методов. В результате отладка точек останова, заданных для имен методов, может быть затронута и не остановлена должным образом. Точки останова номера строк не затрагиваются.

MAM в стеке

Так как интеграция пакета SDK для приложений Intune в значительной степени зависит от замены классов и методов, вы начнете видеть трассировки mam стека. Если в вашем приложении нет учетной записи, предназначенной для политик защиты приложений, весь этот код MAM неактивен: MAMActivity будет работать идентично Activity, onMAMCreate будет работать идентично onCreate, и т. д. Когда вы видите mam в стеке, сначала проверка:

• Предназначена ли учетная запись с помощью политик защиты приложений?
• Установлен ли Корпоративный портал Intune?

Если ответ на оба варианта не будет "да", код MAM действует как простое сквозное руководство.

Какое средство мне нужно?

Если вы создаете приложение с помощью Gradle, см. статью Интеграция с подключаемым модулем сборки Gradle.

Если вы создаете приложение с помощью .NET MAUI, см. статью Интеграция с целевыми объектами .NET MAUI.

Если вы создаете приложение, используя ни один из описанных выше, см. статью Интеграция со средством командной строки.

Интеграция с подключаемым модулем сборки Gradle

Подключаемый модуль пакета SDK для приложений Intune распространяется в составе пакета SDK как GradlePlugin/com.microsoft.intune.mam.build.jar.

Чтобы подключаемый модуль распознался Gradle, его необходимо добавить в путь к классу buildscript . Подключаемый модуль зависит от Javassist, который также необходимо добавить. Дополнительные сведения о зависимости Javassist см. в разделе Зависимости.

Чтобы добавить их в путь к классу, добавьте следующий код в корневой каталог 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")
    }
}

Затем, чтобы применить подключаемый модуль, добавьте в файл модуля приложения следующее build.gradle :

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

По умолчанию подключаемый модуль работает с project зависимостями и внешними библиотеками. Компиляция тестов не затрагивается.

Примечание.

Начиная с пакета SDK для приложений Intune версии 8.0 теперь невозможно обрабатывать библиотеки выборочно. Обрабатываются все библиотеки.

Зависимости

Примечание.

Вы должны использовать версию 3.6.1 или более позднюю для подключаемого модуля Android Gradle и 5.6.4 или более поздней версии Gradle.

Подключаемый модуль Gradle зависит от Javassist, который должен быть доступен для разрешения зависимостей Gradle. Javassist используется только во время сборки при запуске подключаемого модуля, и код Javassist не будет добавлен в приложение.

Примечание.

Версии Javassist могут быть несовместимы с обратной совместимостью. Как правило, следует использовать точную версию, ожидаемую пакетом SDK для приложений Intune:

• Пакет SDK для приложений Intune ≥ 10.0.0 требует javassist 3.29.2-GA
• Пакет SDK для приложений Intune ≥ 7.0.0 требует javassist 3.27.0-GA
• Пакет SDK < для приложений Intune 7.0.0 требует javassist 3.22.0-GA

Кроме того, при использовании пакета SDK MAM версии 8.0.0 и более поздних версий необходимо убедиться, что в конфигурации Gradle задано следующее:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Исключения

Для исключения определенных компонентов приложения из перезаписей могут быть предоставлены дополнительные конфигурации. Исключения в основном полезны для компонентов, которые не относятся к MAM (т. е. не обрабатывают и не отображают корпоративные данные).

Исключения можно настроить для различных областей:

• excludeProjects позволяет исключить список проектов Gradle. Эти исключения полезны для проектов, которые не работают с библиотеками Android или системными API и (или) не обрабатывают корпоративные данные. Например, хорошим кандидатом может быть проект, содержащий исключительно машинный код для выполнения низкоуровневых сетевых операций. Если проект широко взаимодействует с библиотеками Android или системными API, эти исключения следует избегать.
• excludeClasses позволяет исключить список классов. Эти исключения полезны для классов, которые не обрабатывают или не представляют корпоративные данные. Например, хорошие кандидаты — экраны-заставки и устройства Activityподключения. Обратите внимание, что класс нельзя исключить, если обрабатывается какой-либо из его надклассов.
• excludeVariants включает исключение вариантов проекта. Эти исключения могут ссылаться либо на полное имя варианта, либо на один вариант. Они особенно полезны, если вы хотите создать вариант приложения, отличный от MAM. Например, если приложение имеет типы debug сборки и release со вкусами {noMAM, MAM} и {mock, production} можно указать следующее:
  • noMAM , чтобы исключить все варианты со вкусом noMAM или
  • noMAMMockDebug , чтобы исключить только этот точный вариант.

Предостережение

Исключения не должны восприниматься легкомыслительно. Неправильное применение исключений может привести к серьезной утечке данных в приложении. Всегда проверяйте влияние любого исключения, которое вы применяете.

Пример частичной сборки.gradle с исключениями

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

Это приведет к следующим последствиям:

• :product:FooLib не переписывается, так как включается в excludeProjects
• :product:foo-project перезаписывается, за исключением com.contoso.SplashActivity, который пропускается, так как находится в excludeClasses
• com.microsoft.bar:baz.1.0.0 переписывается, так как для обработки включены все внешние библиотеки.
• Варианты со вкусом noMAM не переписываются.

Reporting

Подключаемый модуль сборки может создавать html-отчет об изменениях, которые он вносит. Чтобы запросить создание этого отчета, укажите report = true в блоке конфигурации intunemam . В случае создания отчет будет записан outputs/logs в каталог сборки.

intunemam {
    report = true
}

Проверки

Подключаемый модуль сборки может выполнять дополнительную проверку для поиска возможных ошибок в классах обработки. Эти проверки помогают защититься от потенциальных сбоев среды выполнения, вызванных подключаемым модулем.

Чтобы запросить проверку в сборке, укажите verify = true в блоке конфигурации intunemam . Это может добавить несколько секунд к времени, затраченного задачей подключаемого модуля.

intunemam {
    verify = true
}

Как правило, сбой проверки представляет собой ошибку в подключаемом модуле сборки. Чтобы помочь в случае сбоя, сообщите о проблеме в службу поддержки Майкрософт. Если у вас нет контракта на поддержку Майкрософт, откройте проблему с GitHub.

Добавочные сборки

Чтобы включить поддержку сборки постепенно, укажите incremental = true в блоке конфигурации intunemam . Эта функция повышает производительность сборки, обрабатывая только измененные входные файлы. Конфигурация по умолчанию для incremental — false.

intunemam {
    incremental = true
}

Интеграция с целевыми объектами .NET MAUI

Целевые объекты пакета SDK для приложений Intune распространяются в составе пакета SDK как Microsoft.Intune.Maui.Essentials.android.targets.

Целевые объекты будут автоматически импортированы в приложение во время компиляции после добавления пакета Sdk для приложений Intune для .NET MAUI — Android .

Интеграция со средством сборки из командной строки

Средство сборки из командной строки доступно в папке BuildTool удаления пакета SDK. Он выполняет ту же функцию, что и цели подключаемого модуля Gradle/.NET, описанные выше, но могут быть интегрированы в пользовательские системы сборки. Так как это более универсальное, его сложнее вызывать, поэтому по возможности следует использовать целевые объекты подключаемого модуля Gradle или .NET.

Использование средства Command-Line

Средство командной строки можно вызвать с помощью предоставленных вспомогательных скриптов, расположенных в каталоге BuildTool\bin .

Средство ожидает следующие параметры.

Параметр	Обязательный	Описание
--input	Да	Список jar-файлов и каталогов файлов классов, которые необходимо изменить, с запятой. Сюда должны входить все jar-файлы или каталоги, которые вы планируете переписать.
--output	Да	Список jar-файлов и каталогов с разделителями с запятой, в которые будут храниться измененные классы. На входную запись должна быть одна выходная запись, и они должны быть перечислены по порядку.
--classpath	Да	Путь к классу сборки. Он может содержать как jar-файлы, так и каталоги классов.
--processed	Нет	Разделенный запятой список JAR-файлов и каталогов, содержащих классы, которые уже были обработаны предыдущим вызовом средства сборки.
--excludeClasses	Нет	Список с разделителями с запятой, содержащий имена классов, которые следует исключить из перезаписи.
--report	Нет	Каталог для создания HTML-отчета об измененных классах. Если этот параметр не указан, отчет не записывается.

Необязательный --processed параметр используется для включения добавочных сборок. Набор файлов и каталогов, перечисленных здесь, должен быть несвязан со списками входных данных и классов.

Совет

В unix-подобных системах точка с запятой — это разделитель команд. Чтобы избежать разделения команд в оболочке, обязательно экранируйте каждую точку с запятой с помощью "" или заключите полный параметр в кавычки.

Пример вызова средства 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

Это приведет к следующим последствиям:

• product-foo-project каталог перезаписан вmam-build\product-foo-project
• bar.jar перезаписывается в mam-build\libs\bar.jar
• zap.jarне перезаписывается, так как он указан только в--classpath
• Класс com.contoso.SplashActivityне перезаписывается, даже если он находится в --input

Предупреждение

Средство сборки в настоящее время не поддерживает AAR-файлы. Если система сборки еще не извлекает classes.jar данные при работе с AAR-файлами, это необходимо сделать перед вызовом средства сборки.

Настройка MAMApplication

Если приложение создает подкласс , то средство подключаемого модуля или командной android.app.Applicationстроки сборки преобразует класс приложения.

Если приложение не содержит подкласс android.app.Application, необходимо задать"com.microsoft.intune.mam.client.app.MAMApplication" в качестве атрибута "android:name" в теге <application> AndroidManifest.xml.

Рекомендуемые рекомендации для Android

• Используйте новейшие средства сборки пакета SDK для Android.
• Удалите все ненужные и неиспользуемые библиотеки (например, android.support.v4).

После автоматической замены пакет SDK для приложений Intune по-прежнему поддерживает контракт, предоставляемый API Android. Однако условия сбоя могут активироваться чаще в результате применения политики. Эти рекомендации для Android понизят вероятность сбоя:

• Функции пакета SDK для Android, которые могут возвращать null , теперь имеют более высокую вероятность возврата null. Убедитесь, что null проверки защищают эти вызовы функций.
• Функции, которые можно проверить, например clipboardManager.getPrimaryClipDescription(), должны быть проверены с помощью API-интерфейсов замены MAM, таких как MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Все производные функции должны вызываться к версиям суперкласса.
• Избегайте неоднозначного использования любого API. Например, использование Activity.startActivityForResult без проверки requestCode приведет к странному поведению.

Службы

Применение политики может повлиять на взаимодействие со службой Android. Методы, устанавливающие привязанное подключение к службе, например, Context.bindService могут завершиться сбоем из-за применения базовой политики в Service.onBind и могут привести к ServiceConnection.onNullBinding или ServiceConnection.onServiceDisconnected. Взаимодействие с установленной привязанной службой SecurityException может вызвать исключение из-за принудительного применения политики в Binder.onTransact.

Клиентам связанных служб настоятельно рекомендуется проверка для исключений, создаваемых службой, а не разрешать исключениям распространяться на остальную часть клиентского приложения.

Условия выхода

После настройки подключаемого модуля сборки или интеграции средства командной строки в процесс сборки убедитесь, что он успешно работает:

• Убедитесь, что сборка успешно компилируется и выполняет сборку.
• report Настройте флаг, затем откройте документ отчета и убедитесь, что происходит замена классов и методов:
  • При использовании подключаемого модуля выполните действия, описанные в разделе Отчеты.
  • При использовании программы командной строки добавьте --report флаг .
• Если используется подключаемый модуль, настройте verify флаг и убедитесь, что он не приведет к ошибкам. См. раздел Проверка.
• Дважды проверка все исключения (excludeProjects, excludeClasses, и excludeVariants) в build.gradle. Убедитесь, что каждое исключение необходимо и не связано с защищенными данными. Исторически многие ошибки утечки данных возникали из-за чрезмерно агрессивных исключений.
• Не устанавливая Корпоративный портал Intune, запустите скомпилированное приложение, войдите в систему с помощью Microsoft Entra пользователя, который не предназначен для политики защиты приложений, и убедитесь, что приложение работает должным образом.
  • Выйдите из системы и повторите этот тест с установленным Корпоративный портал Intune.

Вопросы и ответы

Мое приложение ранее интегрировало пакет SDK без подключаемого модуля сборки; как использовать подключаемый модуль сборки?

В более старых версиях пакета SDK для приложений Intune не было автоматизированного способа замены классов и методов, и разработчикам нужно было вручную выполнять эти замены в исходном коде. Если ваше приложение ранее интегрировалось таким образом, можно без каких-либо изменений в исходном коде применить подключаемый модуль сборки (или средство сборки из командной строки). В проекте по-прежнему должен быть указан пакет SDK MAM в качестве зависимости.

Дальнейшие действия

После выполнения всех условий выхода перейдите к этапу 4. Основные компоненты интеграции MAM.