SDK da Aplicação Intune para Android – Introdução à MAM

O SDK da Aplicação Microsoft Intune para Android permite-lhe incorporar Intune políticas de proteção de aplicações na sua aplicação Java/Kotlin Android nativa. Estas políticas também são conhecidas como políticas de MAM. Uma aplicação gerida Intune é uma aplicação integrada no SDK da Aplicação Intune. Quando Intune gere ativamente a aplicação, Intune administradores podem facilmente implementar políticas de proteção de aplicações na sua aplicação gerida Intune.

Fase 3: Introdução com MAM

Objetivos de Fase

• Transfira o SDK da Aplicação Intune.
• Saiba que ficheiros estão incluídos no SDK da Aplicação Intune.
• Faça referência ao SDK da Aplicação Intune na sua aplicação.
• Configure o Plug-in de Compilação do Gradle de Aplicação Intune ou utilize a ferramenta de compilação da linha de comandos.
• Confirme que o SDK da Aplicação Intune está devidamente incluído na sua criação.

Histórico

Agora que a sua aplicação integrou o MSAL com êxito, está na altura de transferir o SDK da Aplicação Intune e incluí-lo no processo de compilação da sua aplicação.

Uma grande parte da integração do SDK da Aplicação Intune está a substituir classes e chamadas de método padrão do Android por Intune versões dessas classes e chamadas de método. O SDK inclui ferramentas de compilação que efetuam automaticamente a maioria destas substituições. Se quiser saber mais sobre esta lógica de substituição, veja a secção substituições de classes e métodos do apêndice.

Transferir o SDK da Aplicação Intune

Para transferir o SDK, veja Transferir os ficheiros do SDK.

O que há no SDK?

O SDK da Aplicação Intune consiste nos seguintes ficheiros:

• Microsoft. Intune. MAM. SDK.aar: os componentes do SDK, exceto os ficheiros JAR da Biblioteca de Suporte.
• com.microsoft.intune.mam.build.jar: um plug-in Gradle, que ajuda na integração do SDK.
• CHANGELOG.md: fornece um registo das alterações efetuadas em cada versão do SDK.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: este Arquivo Android (AAR) contém stubs para classes de sistema Android que estão presentes apenas em dispositivos mais recentes, mas que são referenciados por métodos em MAMActivity. Os dispositivos mais recentes ignoram estas classes stub. Esta AAR só é necessária se a sua aplicação efetuar reflexões sobre as classes derivadas do e a maioria das MAMActivityaplicações não precisar de a incluir. A AAR contém regras ProGuard para excluir todas as respetivas classes.

Referenciar bibliotecas de Aplicações Intune

O SDK da Aplicação Intune é uma biblioteca Android padrão sem dependências externas. Microsoft. Intune. MAM. O SDK.aar contém as interfaces necessárias para ativar as políticas de proteção de aplicações. Também contém o código necessário para interagir com a aplicação Microsoft Intune Portal da Empresa.

Android Studio

Microsoft. Intune. MAM. O SDK.aar tem de ser especificado como uma referência de biblioteca android. Para adicionar esta dependência à sua criação, siga Adicionar o AAR ou JAR como uma dependência da documentação do Android.

Visual Studio

O pacote NuGet do SDK da Aplicação Intune para .NET MAUI – Android tem de ser adicionado como uma dependência.

Siga o processo para Instalar e gerir pacotes no Visual Studio com o Gestor de Pacotes NuGet.

O Microsoft.Intune. MAM. O SDK.aar está vinculado a criar referências C# no âmbito do Microsoft.Intune.Mam espaço de nomes.

ProGuard

A sua aplicação pode já utilizar o ProGuard (ou qualquer outro mecanismo de redução/ocultação) como um passo de compilação. O SDK da Aplicação Intune tem regras de configuração ProGuard que têm de ser incluídas nesse passo de compilação. Incluindo o . A AAR na sua compilação, conforme descrito anteriormente, integra automaticamente a configuração do SDK no passo ProGuard, para que os ficheiros de classe necessários sejam mantidos. Se tiver incluído o . AAR, não é necessária qualquer outra alteração.

A Biblioteca de Autenticação da Microsoft (MSAL) é fornecida com a sua própria configuração ProGuard. Se a sua aplicação integrar a MSAL, consulte a documentação da MSAL para obter mais detalhes.

Criar ferramentas

O SDK fornece ferramentas de compilação (um plug-in para compilações do Gradle, destinos para compilações .NET e uma ferramenta de linha de comandos) que executam substituições de MAM automaticamente. Estas ferramentas transformam os ficheiros de classe gerados pela compilação Java; não modificam o código fonte original. Tem de utilizar o plug-in gradle, o pacote NuGet .NET ou a ferramenta de linha de comandos.

As ferramentas de compilação por si só não são suficientes para integrar totalmente a sua aplicação. As ferramentas executam apenas substituições de classes e métodos . Não efetuam integrações mais complexas do SDK, como Identidades Múltiplas, Registo da Política de Proteção de Aplicações, Política para limitar a transferência de dados entre aplicações e localizações de armazenamento na cloud ou de dispositivos ou msal. Tem de concluir estas integrações antes de a aplicação estar totalmente Intune ativada. Reveja cuidadosamente o resto desta documentação para obter pontos de integração relevantes para a sua aplicação.

Depuração

A ferramenta de compilação executa substituições após a compilação. Estas substituições alteram alguns nomes de métodos. Como resultado, a depuração de pontos de interrupção definidos nos nomes dos métodos pode ser afetada. Podem não parar como esperado. Os pontos de interrupção do número de linha não são afetados.

MAM na Pilha

A integração do SDK da Aplicação Intune depende bastante das substituições de classes e métodos. Devido a esta dependência, verá mam em todos os rastreios de pilha. Quando a sua aplicação não tem uma conta direcionada para as políticas de proteção de aplicações, todo este código MAM fica inativo. Por exemplo, MAMActivity funciona de forma idêntica a Activity e onMAMCreate funciona de forma idêntica a onCreate. Sempre que vir mam numa pilha, primeiro marcar:

• A conta é direcionada com políticas de proteção de aplicações?
• O Portal da Empresa do Intune está instalado?

A menos que a resposta a ambos seja "sim", o código MAM funciona como pass-through simples.

De que ferramenta preciso?

Se criar a sua aplicação com o Gradle, veja Integrar com o Plug-in de Criação do Gradle

Se criar a sua aplicação com o .NET MAUI, veja Integrating with the .NET MAUI Targets (Integrar com os Destinos MAUI do .NET).

Se criar a sua aplicação sem nenhuma das ferramentas anteriores, veja Integrar com a Ferramenta de Linha de Comandos.

Integrar com o Plug-in de Criação do Gradle

O plug-in do SDK da Aplicação Intune é distribuído como parte do SDK como GradlePlugin/com.microsoft.intune.mam.build.jar.

Para que o plug-in seja reconhecido pelo Gradle, tem de ser adicionado ao caminho da buildscript classe. O plug-in depende do Javassist, que também tem de ser adicionado. Para obter mais informações sobre a dependência javassist, veja Dependências.

Para adicioná-los ao classpath, adicione o seguinte à sua raiz 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")
    }
}

Em seguida, para aplicar o plug-in, adicione o seguinte ao ficheiro para a build.gradle sua aplicação e módulos de funcionalidade dinâmicos:

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

Por predefinição, o plug-in funciona em project dependências e bibliotecas externas. A compilação de teste não é afetada.

Dependências

O plug-in do Gradle tem uma dependência do Javassist, que tem de ser disponibilizado para a resolução de dependências do Gradle. O Javassist é utilizado apenas no momento da criação quando executa o plug-in e não é adicionado nenhum código Javassist à sua aplicação.

Matriz de Compatibilidade

O Plug-in de Criação do SDK MAM está alinhado com os requisitos de criação e as tabelas de compatibilidade do Android. As versões não listadas aqui podem ou não funcionar.

Exclusões

Podem ser fornecidas mais configurações para excluir componentes específicos na sua aplicação de reescritas. As exclusões são predominantemente úteis para componentes que não são relevantes para MAM (ou seja, não processam nem apresentam dados empresariais).

As exclusões podem ser configuradas para diferentes âmbitos:

• excludeProjects permite excluir uma lista de projetos do Gradle. Estas exclusões são úteis para projetos que não interagem com bibliotecas Android ou APIs de sistema. Também são úteis para projetos que não processam dados empresariais. Por exemplo, um projeto que contenha exclusivamente código nativo para realizar operações de rede de baixo nível pode ser um bom candidato. Se um projeto interagir amplamente com bibliotecas Android ou APIs de sistema, evite estas exclusões.
• excludeClasses permite excluir uma lista de classes. Estas exclusões são úteis para classes que não processam ou apresentam dados empresariais. Por exemplo, os ecrãs de salpicos e a integração Activitys são bons candidatos. Uma classe não pode ser excluída se alguma das suas superclasses for processada.
• excludeVariants ativa a exclusão de variantes de projeto. Estas exclusões podem referir-se a um nome de variante completo ou a um único sabor. São especialmente úteis se quiser criar um sabor não MAM da sua aplicação. Por exemplo, se a sua aplicação tiver tipos debug de criação e release com sabores {noMAM, MAM} e {mock, production} pode especificar:
  • noMAM para excluir todas as variantes com o sabor noMAM ou
  • noMAMMockDebug para excluir apenas essa variante exata.

Exemplo de build.gradle parcial com exclusões

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

Isto teria os seguintes efeitos:

• :product:FooLib não é reescrito porque está incluído no excludeProjects
• :product:foo-project é reescrito, exceto para com.contoso.SplashActivity, que é ignorado porque está em excludeClasses
• com.microsoft.bar:baz.1.0.0 é reescrito porque todas as bibliotecas externas estão incluídas para processamento.
• As variantes com o noMAM sabor não são reescritas.

Reporting

O plug-in de compilação pode gerar um relatório html das alterações efetuadas. Para pedir a geração deste relatório, especifique report = true no intunemam bloco de configuração. Se for gerado, o relatório é escrito outputs/logs no diretório build.

intunemam {
    report = true
}

Verificação

O plug-in de compilação pode executar mais verificações para procurar possíveis erros nas classes de processamento. Estas verificações ajudam a proteger contra potenciais falhas de runtime induzidas pelo plug-in.

Para pedir a verificação na compilação, especifique verify = true no intunemam bloco de configuração. Isto pode adicionar vários segundos ao tempo que a tarefa do plug-in demorou.

intunemam {
    verify = true
}

Geralmente, uma falha de verificação representa um erro no plug-in de compilação. Para obter assistência com uma falha, reencave o problema com o suporte da Microsoft. Se não tiver um contrato de suporte da Microsoft, abra um problema do GitHub.

Compilações incrementais

Para ativar o suporte para a criação incremental, especifique incremental = true no intunemam bloco de configuração. Esta funcionalidade aumenta o desempenho da compilação ao processar apenas os ficheiros de entrada que são alterados. A configuração predefinida para incremental é false.

intunemam {
    incremental = true
}

Configuração do Módulo de Funcionalidade Dinâmica

Os Módulos de Funcionalidades Dinâmicas são criados separadamente do projeto da aplicação. Como tal, os Módulos de Funcionalidades Dinâmicas também têm de aplicar o Plug-in de Criação do Gradle.

O plug-in do Gradle tem limitações técnicas nas APIs que utiliza. Devido a estas limitações, as classes de aplicações têm de ser reprocessadas ao transformar classes de módulos de funcionalidades dinâmicas. Para garantir que este reprocessamento pode ser feito, configure todos os módulos de funcionalidades com as mesmas definições que a aplicação.

Por exemplo, se uma aplicação excluir uma classe, o módulo de funcionalidade dinâmica também deve excluir essa classe.

Integrar com os Destinos MAUI do .NET

Os destinos do SDK da Aplicação Intune são distribuídos como parte do SDK como Microsoft.Intune. Maui.Essentials.android.targets.

Os destinos são importados automaticamente para a sua aplicação no momento da compilação assim que o pacote NuGet do SDK da Aplicação Intune para .NET MAUI – Android for adicionado.

Integrar com a Ferramenta de Compilação da Linha de Comandos

A ferramenta de compilação da linha de comandos está disponível na BuildTool pasta da remoção do SDK. Executa a mesma função que o plug-in gradle e os destinos .NET detalhados acima. No entanto, a ferramenta de linha de comandos pode ser integrada em sistemas de compilação personalizados. Uma vez que a ferramenta é mais genérica, é mais complexo invocar. Utilize o plug-in do Gradle ou destinos .NET sempre que possível.

Utilizar a Ferramenta de Command-Line

A ferramenta de linha de comandos pode ser invocada através dos scripts auxiliares fornecidos localizados no BuildTool\bin diretório.

A ferramenta espera os seguintes parâmetros.

A opção opcional --processed é utilizada para ativar compilações incrementais. O conjunto de ficheiros/diretórios listado aqui deve estar desa contíguo às listas de entrada e classpath.

Invocação da Ferramenta Command-Line de Exemplo

> 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

Isto teria os seguintes efeitos:

• o product-foo-project diretório é reescrito para mam-build\product-foo-project
• bar.jar é reescrito para mam-build\libs\bar.jar
• zap.jar não é reescrito porque está listado apenas em--classpath
• A com.contoso.SplashActivity classe não é reescrita mesmo que esteja em --input

Definir MAMApplication

Se a sua aplicação criar uma subclasse de android.app.Application, a ferramenta de compilação plug-in ou linha de comandos transforma a sua classe de aplicação.

Se a sua aplicação não subclasse android.app.Application, tem de definir "com.microsoft.intune.mam.client.app.MAMApplication" como o "android:name" atributo na etiqueta da <application> sua AndroidManifest.xml.

Melhores práticas recomendadas para Android

• Utilize as mais recentes ferramentas de compilação do SDK Android.
• Remova todas as bibliotecas desnecessárias e não utilizadas (por exemplo, android.support.v4).

Depois de efetuar substituições automáticas, o SDK da Aplicação Intune mantém o contrato fornecido pela API para Android. No entanto, as condições de falha podem ser acionadas com mais frequência devido à imposição de políticas. Estas melhores práticas do Android reduzem a probabilidade de falha:

• As funções do SDK Android que podem ser devolvidas null têm agora uma maior probabilidade de devolver null. Certifique-se de que null verifica a proteção destas chamadas de função.
• As funcionalidades que podem ser verificadas, como clipboardManager.getPrimaryClipDescription(), têm de ser verificadas através das respetivas APIs de substituição de MAM, como MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Todas as funções derivadas têm de chamar as respetivas versões de superclasse.
• Evite a utilização de qualquer API de forma ambígua. Por exemplo, utilizar Activity.startActivityForResult sem verificar as requestCode causas é um comportamento estranho.

Serviços

A imposição de políticas pode afetar as interações do Serviço Android. Os métodos que estabelecem uma ligação de serviço vinculada, como Context.bindService , por exemplo, podem falhar devido à imposição da política subjacente no Service.onBind e podem resultar em ServiceConnection.onNullBinding ou ServiceConnection.onServiceDisconnected. Interagir com um serviço vinculado estabelecido pode gerar um SecurityException devido à imposição de política no Binder.onTransact.

Os clientes de serviços vinculados são encorajados a marcar para exceções emitidas pelo serviço. Não permita que as exceções se propaguem para o resto da aplicação cliente.

Critérios de Saída

Depois de configurar o plug-in de compilação ou integrar a ferramenta de linha de comandos no processo de compilação, confirme que está a ser executado com êxito:

• Certifique-se de que a compilação compila e compila com êxito.
• Configure o report sinalizador e, em seguida, abra o documento do relatório e confirme se estão a ocorrer substituições de classes e métodos:
  • Se estiver a utilizar o plug-in, siga os passos em Relatórios.
  • Se estiver a utilizar a ferramenta de linha de comandos, inclua o --report sinalizador.
• Se estiver a utilizar o plug-in, configure o verify sinalizador e certifique-se de que não produz erros. Veja Verificação.
• Faça duplo marcar todas as exclusões (excludeProjects, excludeClassese excludeVariants) em build.gradle. Confirme que cada exclusão é necessária e não lida com dados protegidos. Historicamente, ocorrem muitos erros de fuga de dados devido a exclusões demasiado agressivas.
• Sem o Portal da Empresa do Intune instalado, inicie a sua aplicação compilada. Inicie sessão com um utilizador Microsoft Entra que não seja visado pela Política de Proteção de Aplicações. Confirme que a aplicação funciona conforme esperado.
  • Termine sessão e repita este teste com o Portal da Empresa do Intune instalado.

Perguntas frequentes

A minha aplicação integrou anteriormente o SDK sem o plug-in de compilação; como posso utilizar o plug-in de criação?

As versões mais antigas do SDK da Aplicação Intune não incluíam nenhuma forma automatizada de realizar substituições de classes e métodos. Os programadores precisavam de realizar estas substituições manualmente no código fonte. Se a sua aplicação estiver integrada desta forma, é seguro aplicar o plug-in de compilação ou a ferramenta de compilação da linha de comandos. Não precisa de modificações ao código fonte. O projeto ainda tem de listar o SDK de MAM como uma dependência.

Próximas etapas

Depois de concluir todos os Critérios de Saída, avance para a Fase 4: Integração de MAM – Versão Essentials.