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

Пакет SDK для приложений Microsoft Intune для Android позволяет внедрять политики защиты приложений Intune в родное приложение Java/Kotlin для Android. Эти политики также называются политиками MAM. Приложение, управляемое Intune, интегрировано с пакетом SDK для приложений Intune. Если Intune активно управляет приложением, администраторы Intune могут легко развернуть политики защиты приложений в приложении, управляемом Intune.

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

Цели этапа

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

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

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

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

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

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

Содержимое пакета SDK?

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

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

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

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

Android Studio

Корпорация Майкрософт. Intune. МАМ. SDK.aar должен быть указан как ссылка на библиотеку Android. Сведения о том, как добавить эту зависимость в вашу сборку, см. в разделе Добавление AAR или JAR в качестве зависимости из документации Android.

Visual Studio

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

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

Microsoft.Intune. МАМ. 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 Intune?

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

Какой инструмент мне нужен?

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

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

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

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

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

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

Чтобы добавить их в classpath, добавьте в корневой 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 зависимостями и внешними библиотеками. Это не влияет на компиляцию тестов.

Зависимости

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

Матрица совместимости

Подключаемый модуль для сборки MAM SDK соответствует требованиям к сборкам Android и таблицам совместимости. Версии, не перечисленные здесь, могут работать, а могут и не работать.

Исключения

Можно предоставить дополнительные конфигурации, чтобы исключить определенные компоненты в приложении из возможности переписывания. Исключения в основном полезны для компонентов, которые не относятся к 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
}

Проверка

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

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

intunemam {
    verify = true
}

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

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

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

intunemam {
    incremental = true
}

Динамическая конфигурация модуля компонентов

Модули динамических компонентов создаются отдельно от проекта приложения. Таким образом, к модулям динамических функций также необходимо применить подключаемый модуль Gradle Build.

Подключаемый модуль Gradle имеет технические ограничения в используемых им API. Из-за этих ограничений классы приложений необходимо повторно обрабатывать при преобразовании классов динамических модулей признаков. Чтобы обеспечить возможность повторной обработки, настройте все модули функций с теми же настройками, что и приложение.

Например, если приложение исключает класс, модуль динамической функции также должен исключить этот класс.

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

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

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

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

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

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

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

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

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

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

Настройка MAMApplication

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

Если ваше приложение не является подклассом 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 снижают вероятность сбоя:

• Функции Android SDK, которые могут возвращать 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 Intune.

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

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

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

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

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