通过

Intune适用于 Android 的应用 SDK - MAM 入门

  • 项目

Microsoft Intune App SDK for Android 允许将Intune应用保护策略 (也称为 APP 或 MAM 策略) 合并到本机 Java/Kotlin Android 应用中。 Intune托管的应用程序是与 Intune App SDK 集成的应用程序。 当Intune主动管理应用时，Intune管理员可以轻松地将应用保护策略部署到Intune托管的应用。

注意

本指南分为几个不同的阶段。 首先查看 第 1 阶段：规划集成。

第 3 阶段：使用 MAM 入门

阶段Goals

  • 下载Intune应用 SDK。
  • 了解 Intune App SDK 中包含的文件。
  • 在应用程序中引用Intune应用 SDK。
  • 配置 Intune 应用 Gradle 生成插件或使用命令行生成工具。
  • 确认Intune应用 SDK 已正确包含在生成中。

背景

现在，应用程序已成功集成 MSAL，接下来可以下载 Intune 应用 SDK 并将其包含在应用程序的生成过程中。

集成 Intune App SDK 的很大一部分是将标准 Android 类和方法调用替换为这些类和方法调用的Intune版本。 SDK 包含生成工具，可自动为你完成大部分替换。 若要了解有关此替换逻辑的详细信息，请参阅附录的类和方法替换部分。

下载 Intune 应用 SDK

若要下载 SDK，请参阅 下载 SDK 文件。

SDK 中有哪些内容？

Intune应用 SDK 包含以下文件：

  • Microsoft。Intune。妈妈。SDK.aar：SDK 组件，支持库 JAR 文件除外。
  • com.microsoft.intune.mam.build.jar：有助于 集成 SDK 的 Gradle 插件。
  • CHANGELOG.md：提供在每个 SDK 版本中所做的更改的记录。
  • THIRDPARTYNOTICES.TXT：确认将编译到应用中的第三方和/或 OSS 代码的归属通知。
  • Microsoft。Intune。妈妈。SDK。DownlevelStubs.aar：此 AAR 包含 Android 系统类的存根，这些存根仅存在于较新的设备上，但由 MAMActivity 中的方法引用。 较新的设备忽略这些存根类。 仅当应用对派生自 MAMActivity的类执行反射，并且 大多数应用不需要包含它时，才需要此 AAR。 AAR 包含用于排除其所有类的 ProGuard 规则。

引用Intune应用库

Intune应用 SDK 是标准 Android 库，没有外部依赖项。 Microsoft。Intune。妈妈。SDK.aar 包含启用应用保护策略所需的接口，以及与 Microsoft Intune 公司门户 应用互操作所需的代码。

Android Studio

Microsoft。Intune。妈妈。SDK.aar 必须指定为 Android 库引用。 若要将此依赖项添加到生成，请按照从 Android 文档中 添加 AAR 或 JAR 作为依赖项 进行操作。

Visual Studio

Intune应用 SDK for .NET MAUI - Android NuGet 包必须添加为依赖项。

按照 使用 NuGet 包管理器在 Visual Studio 中安装和管理包的过程进行操作。

Microsoft.Intune。妈妈。SDK.aar 绑定到创建范围限定为命名空间的 Microsoft.Intune.Mam C# 引用。

ProGuard

应用程序可能已使用 ProGuard (或任何其他收缩/模糊处理机制) 作为生成步骤。 Intune App SDK 具有必须包含在生成步骤中的 ProGuard 配置规则。 包括 。 如上所述，生成中的 AAR 会自动将 SDK 的配置集成到 ProGuard 步骤中，以便保留必要的类文件。 如果已正确包含 。AAR，无需进行其他更改。

Microsoft身份验证库 (MSAL) 附带其自己的 ProGuard 配置。 如果应用集成了 MSAL，请参阅 MSAL 文档 了解更多详细信息。

生成工具

SDK 提供生成工具 (用于 Gradle 生成的插件、用于 .NET 生成的目标，以及自动执行 MAM 替换的命令行工具) 。 这些工具转换 Java 编译生成的类文件;它们不会修改原始源代码。 需要使用 Gradle 插件、.NET NuGet 包或命令行工具。

仅使用生成工具不足以完全集成应用程序。 这些工具仅执行 类和方法替换 。 它们不会执行任何更复杂的 SDK 集成，例如多标识、注册应用保护策略、限制应用和设备或云存储位置之间的数据传输的策略，或者 MSAL 配置，这些集成必须在应用完全Intune启用之前完成。 请仔细查看本文档的其余部分，了解与应用相关的集成点。

对调试的影响

生成工具在编译后执行替换，这将更改某些方法名称。 因此，对方法名称设置的断点调试可能会受到影响，并且不会按预期停止。 行号断点不受影响。

堆栈中的 MAM

由于Intune应用 SDK 集成在很大程度上依赖于类和方法替换，因此你将开始看到mam整个堆栈跟踪。 当应用没有针对应用保护策略的帐户时，所有这些 MAM 代码都处于休眠状态：MAMActivity将工作方式与 Activity相同，onMAMCreate工作方式与 等相同onCreate。每当在mam堆栈中看到时，首先检查：

  • 帐户是否面向应用保护策略？
  • 是否安装了Intune 公司门户？

除非两者的回答均为“是”，否则 MAM 代码将充当简单的直通。

我需要什么工具？

如果使用 Gradle 生成应用，请参阅 与 Gradle 生成插件集成

如果使用 .NET MAUI 生成应用，请参阅 与 .NET MAUI 目标集成。

如果构建应用时未使用上述任一项，请参阅 与命令行工具集成。

与 Gradle 生成插件集成

Intune应用 SDK 插件作为 GradlePlugin/com.microsoft.intune.mam.build.jar 作为 SDK 的一部分分发。

为了使插件可由 Gradle 识别，必须将其添加到 buildscript 类路径。 插件依赖于 Javassist，还必须添加 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 依赖项和外部库进行操作。 测试编译不受影响。

注意

从 8.0 Intune 应用 SDK 开始，不再可以有选择地处理库。 将处理所有库。

相关性

注意

必须使用版本 3.6.1 或更高版本的 Android Gradle 插件和 Gradle 5.6.4 或更高版本。

Gradle 插件依赖于 Javassist，它必须可用于 Gradle 的依赖项解析。 Javassist 仅在生成时使用，运行插件时不会向应用添加任何 Javassist 代码。

注意

Javassist 版本可能无法向后兼容。 通常，应使用 Intune App SDK 所需的确切版本：

  • Intune应用 SDK ≥ 10.0.0 需要 Javassist 3.29.2-GA
  • Intune App SDK ≥ 7.0.0 需要 Javassist 3.27.0-GA
  • Intune App SDK < 7.0.0 需要 Javassist 3.22.0-GA

此外，在使用 MAM SDK 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 以仅排除该确切的变体。

警告

排除项不应掉以轻心。 错误地应用排除项可能会导致应用中出现严重的数据泄漏。 始终验证应用的任何排除项的影响。

包含排除项的部分 build.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 报告。 若要请求生成此报表，请在配置块中intunemam指定report = true。 如果生成，报表将写入 outputs/logs 生成目录中。

intunemam {
    report = true
}

验证

生成插件可以运行其他验证，以查找处理类中可能存在的错误。 这些检查有助于防止潜在的插件引发的运行时故障。

若要请求在生成中执行验证，请在配置块中intunemam指定verify = true。 这可能会使插件的任务花费的时间增加几秒钟。

intunemam {
    verify = true
}

通常，验证失败表示生成插件中的 bug。 有关故障的帮助，请向Microsoft支持部门上报问题。 如果没有Microsoft支持合同， 请提交 GitHub 问题。

增量生成

若要启用对增量生成的支持，请在配置块中intunemam指定incremental = true。 此功能通过仅处理已更改的输入文件来提高生成性能。 的默认配置 incremental 为 false。

intunemam {
    incremental = true
}

动态功能模块配置

动态功能模块独立于应用项目生成。 因此，动态功能模块还需要应用 Gradle 生成插件。

由于 Gradle 插件使用的 API 中的技术限制，转换动态功能模块类时需要重新处理应用类。 若要确保可以执行此操作，所有功能模块的配置应与它所设计的应用相同的设置。

例如，如果应用排除某个类，动态功能模块也应排除该类。

与 .NET MAUI 目标集成

Intune应用 SDK 目标作为 Microsoft.Intune 作为 SDK 的一部分分发。毛 伊 岛。Essentials.android.targets。

添加适用于 .NET MAUI 的 Intune 应用 SDK - Android NuGet 包后，目标将在编译时自动导入到应用程序中。

与命令行生成工具集成

命令行生成工具在 BuildTool SDK 放置的 文件夹中可用。 它执行的功能与上面详述的 Gradle 插件/.NET 目标相同，但可以集成到自定义生成系统中。 由于它更通用，因此调用起来更复杂，因此应尽可能使用 Gradle 插件/.NET 目标。

使用 Command-Line 工具

可以使用目录中 BuildTool\bin 提供的帮助程序脚本调用命令行工具。

该工具需要以下参数。

参数 必需 说明
--input 是 jar 文件和要修改的类文件的目录的分号分隔列表。 这应包括要重写的所有 jar/目录。
--output 是 用于存储修改后的类的 jar 文件和目录的分号分隔列表。 每个输入条目应有一个输出条目，并且它们应按顺序列出。
--classpath 是 生成类路径。 这可能同时包含 jar 和类目录。
--processed 否 一个以分号分隔的 jar 文件和目录列表，其中包含已由生成工具的先前调用处理的类。
--excludeClasses 否 一个分号分隔的列表，其中包含应从重写中排除的类的名称。
--report 否 用于向其写入有关已修改类的 HTML 报表的目录。 如果未指定，则不会写入任何报表。

可选 --processed 选项用于启用增量生成。 此处列出的文件/目录集应与输入列表和类路径列表不相交。

提示

在类似 Unix 的系统上，分号是命令分隔符。 若要避免 shell 拆分命令，请确保使用“”对每个分号进行转义，或用引号将完整参数括起来。

示例 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 文件。 如果生成系统在处理 aar 文件时尚未提取 classes.jar ，则需要在调用生成工具之前执行此操作。

设置 MAMApplication

如果应用创建了 的 android.app.Application子类，则生成插件/命令行工具将转换应用程序类。

如果应用没有子类 android.app.Application，则必须在 AndroidManifest.xml 的 <application> 标记中将 设置为"com.microsoft.intune.mam.client.app.MAMApplication""android:name" 属性。

  • 使用最新的 Android SDK 生成工具。
  • 删除所有不必要的和未使用的库 (，例如 android.support.v4) 。

执行自动替换后，Intune应用 SDK 仍会维护 Android API 提供的合同。 但是，由于策略强制实施，可能会更频繁地触发失败条件。 以下 Android 最佳做法将降低失败的可能性：

  • 现在可返回 null 的 Android SDK 函数返回 的可能性 null更高。 确保 null 检查保护这些函数调用。
  • 必须通过其 MAM 替换 API（如 ）检查可检查 clipboardManager.getPrimaryClipDescription()的功能，例如 MAMClipboard.getPrimaryClipDescription(clipboardManager)。
  • 任何派生函数都必须通过 调用其超级类版本。
  • 避免以不明确的方式使用任何 API。 例如，在不检查 requestCode 的情况下使用 Activity.startActivityForResult 将导致异常行为。

服务

策略实施可能会影响 Android 服务 交互。 建立绑定服务连接的方法（例如） Context.bindService 可能由于 中 Service.onBind 的基础策略强制实施而失败，并可能导致 ServiceConnection.onNullBinding 或 ServiceConnection.onServiceDisconnected。 由于 在 中Binder.onTransact强制实施策略，SecurityException与已建立的绑定服务交互可能会引发 。

强烈建议绑定服务的客户端检查服务引发的异常，而不是让异常传播到客户端应用程序的其余部分。

退出条件

配置生成插件或将命令行工具集成到生成过程中后，验证它是否成功运行：

  • 确保生成成功编译和生成。
  • 配置 标志 report ，然后打开报表文档并确认发生类和方法替换：
    • 如果使用插件，请按照 报告中的步骤操作。
    • 如果使用命令行工具，请 --report 包括 标志。
  • 如果使用插件，请 verify 配置 标志并确保它不会产生错误。 请参阅 验证。
  • double 检查 build.gradle 中所有排除项 (excludeProjects、 excludeClasses和 excludeVariants) 。 确认每个排除都是必要的，并且不处理受保护的数据。 从历史上看，由于过度攻击性排除，发生了许多数据泄漏错误。
  • 如果不安装Intune 公司门户，请启动已编译的应用，使用应用保护策略不面向的Microsoft Entra用户登录，并确认应用按预期运行。
    • 注销并重复此测试，并安装Intune 公司门户。

常见问题

我的应用以前没有生成插件就集成了 SDK;如何使用生成插件？

旧版 Intune App SDK 不包含任何自动执行类和方法替换的方法，开发人员需要在源代码中手动执行这些替换。 如果应用以前以这种方式集成，则可以安全地) 应用生成插件 (或命令行生成工具，而无需进行任何源代码修改。 项目仍必须将 MAM SDK 列为依赖项。

后续步骤

完成所有退出条件后，继续学习阶段 4：MAM 集成Essentials。