SDK do aplicativo do Intune para Android – Introdução ao MAM

O SDK do Aplicativo do Microsoft Intune para Android permite que você incorpore políticas de proteção do aplicativo do Intune ao seu aplicativo Android nativo Java/Kotlin. Essas políticas também são conhecidas como políticas de MAM. Um aplicativo gerenciado do Intune é aquele que é integrado ao SDK do aplicativo do Intune. Quando o Intune gerencia ativamente o aplicativo, os administradores do Intune podem facilmente implantar políticas de proteção de aplicativo em seu aplicativo gerenciado pelo Intune.

Etapa 3: Introdução ao MAM

Objetivos do Estágio

• Baixe o SDK do aplicativo do Intune.
• Saiba quais arquivos estão incluídos no SDK do aplicativo do Intune.
• Consulte o SDK do aplicativo do Intune em seu aplicativo.
• Configure o Plug-in de Build do Gradle do Aplicativo do Intune ou use a ferramenta de build de linha de comando.
• Confirme se o SDK do aplicativo do Intune está incluído corretamente em sua compilação.

Histórico

Agora que seu aplicativo integrou a MSAL com êxito, é hora de baixar o SDK do aplicativo do Intune e incluí-lo no processo de build do aplicativo.

Uma grande parte da integração do SDK do Aplicativo do Intune está substituindo as classes padrão do Android e as chamadas de método pelas versões do Intune dessas classes e chamadas de método. O SDK inclui ferramentas de compilação que fazem automaticamente a maioria dessas substituições para você. Se você quiser saber mais sobre essa lógica de substituição, consulte a seção substituições de classe e método do apêndice.

Baixar o SDK do aplicativo do Intune

Para baixar o SDK, consulte Baixar os arquivos do SDK.

O que há no SDK?

O SDK do aplicativo do Intune consiste nos seguintes arquivos:

• Microsoft. Intune. MAM. SDK.aar: os componentes do SDK, exceto os arquivos JAR da Biblioteca de Suporte.
• com.microsoft.intune.mam.build.jar: um plug-in do Gradle, que ajuda na integração do SDK.
• CHANGELOG.md: Fornece um registro das alterações feitas em cada versão do SDK.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: este Arquivo Android (AAR) contém stubs para classes do sistema Android que estão presentes apenas em dispositivos mais recentes, mas são referenciados por métodos em MAMActivity. Dispositivos mais recentes ignoram essas classes de stub. Esse AAR será necessário somente se o aplicativo executar reflexão sobre classes derivadas de MAMActivity, e a maioria dos aplicativos não precisar incluí-lo. O AAR contém regras do ProGuard para excluir todas as suas classes.

Referenciar bibliotecas de aplicativos do Intune

O SDK do aplicativo do Intune é uma biblioteca padrão do Android sem dependências externas. Microsoft. Intune. MAM. SDK.aar contém as interfaces necessárias para habilitar políticas de proteção de aplicativo. Ele também contém o código necessário para interoperar com o aplicativo Microsoft Intune Portal da Empresa.

Android Studio

Microsoft. Intune. MAM. SDK.aar deve ser especificado como uma referência de biblioteca do Android. Para adicionar essa dependência ao seu build, siga Adicionar seu AAR ou JAR como uma dependência da documentação do Android.

Visual Studio

O SDK do Aplicativo do Intune para .NET MAUI - pacote NuGet do Android deve ser adicionado como uma dependência.

Siga o processo para Instalar e gerenciar pacotes no Visual Studio usando o Gerenciador de Pacotes NuGet.

O arquivo Microsoft.Intune. MAM. SDK.aar é associado para criar referências C# com escopo para o Microsoft.Intune.Mam namespace.

ProGuard

Seu aplicativo já pode usar o ProGuard (ou qualquer outro mecanismo de redução/ofuscação) como uma etapa de compilação. O SDK do aplicativo do Intune tem regras de configuração do ProGuard que devem ser incluídas nessa etapa de compilação. Incluindo o domínio . O AAR em seu build, conforme descrito anteriormente, integra automaticamente a configuração do SDK à etapa do ProGuard, para que os arquivos de classe necessários sejam mantidos. Se você incluiu o . AAR, nenhuma outra alteração é necessária.

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

Ferramentas de criação

O SDK fornece ferramentas de build (um plug-in para builds do Gradle, destinos para builds do .NET e uma ferramenta de linha de comando) que executam substituições de MAM automaticamente. Essas ferramentas transformam os arquivos de classe gerados pela compilação Java; Eles não modificam o código-fonte original. Você precisa usar o plug-in do Gradle, o pacote .NET NuGet ou a ferramenta de linha de comando.

As ferramentas de compilação por si só não são suficientes para integrar totalmente seu aplicativo. As ferramentas executam apenas substituições de classe e método . Eles não executam nenhuma integração mais complexa do SDK, como Multi-Identidade, Política de Registro para Proteção de Aplicativos, Política para limitar a transferência de dados entre aplicativos e dispositivos ou locais de armazenamento em nuvem ou configuração MSAL. Você deve concluir essas integrações antes que seu aplicativo esteja totalmente habilitado para o Intune. Examine cuidadosamente o restante desta documentação para ver os pontos de integração relevantes para seu aplicativo.

Depuração

As ferramentas de construção executam substituições após a compilação. Essas substituições alteram alguns nomes de método. Como resultado, a depuração de pontos de interrupção definidos em nomes de método pode ser afetada. Eles podem não parar como esperado. Os pontos de interrupção de número de linha não são afetados.

MAM na pilha

A integração do SDK do aplicativo do Intune depende muito de substituições de classe e método. Devido a essa dependência, você vê mam em todos os rastreamentos de pilha. Quando seu aplicativo não tem uma conta direcionada com políticas de proteção de aplicativo, todo esse código MAM fica inativo. Por exemplo, MAMActivity funciona de forma idêntica a Activity e onMAMCreate funciona idêntica a onCreate. Sempre que você vir mam em uma pilha, primeiro marque:

• A conta é alvo de políticas de proteção do aplicativo?
• O Portal da Empresa do Intune está instalado?

A menos que a resposta para ambos seja "sim", o código MAM atua como uma passagem simples.

De qual ferramenta eu preciso?

Se você criar seu aplicativo com o Gradle, consulte Integração com o Plug-in de compilação do Gradle

Se você criar seu aplicativo com o .NET MAUI, consulte Integração com os destinos do .NET MAUI.

Se você criar seu aplicativo com nenhuma das ferramentas anteriores, consulte Integrando com a Ferramenta de Linha de Comando.

Integração com o plug-in de compilação do Gradle

O plug-in do SDK do aplicativo Intune é distribuído como parte do SDK como GradlePlugin/com.microsoft.intune.mam.build.jar.

Para que o plug-in seja reconhecido pelo Gradle, ele deve ser adicionado ao buildscript classpath. O plugin depende do Javassist, que também deve ser adicionado. Para obter mais informações sobre a dependência do Javassist, consulte 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 arquivo para build.gradle seu aplicativo e módulos de recursos dinâmicos:

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

Por padrão, o plug-in opera 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 deve ser disponibilizada para a resolução de dependências do Gradle. O Javassist é usado exclusivamente no momento da compilação ao executar o plug-in e nenhum código do Javassist é adicionado ao seu aplicativo.

Matriz de Compatibilidade

O plug-in de build do MAM SDK se alinha aos requisitos de build do Android e às tabelas de compatibilidade. As versões não listadas aqui podem ou não funcionar.

Exclusões

Mais configurações podem ser fornecidas para excluir componentes específicos em seu aplicativo de reescritas. As exclusões são predominantemente úteis para componentes que não são relevantes para o MAM (ou seja, não manipulam nem exibem dados corporativos).

As exclusões podem ser configuradas para vários escopos:

• excludeProjects permite excluir uma lista de projetos do Gradle. Essas exclusões são úteis para projetos que não fazem interface com bibliotecas do Android ou APIs do sistema. Eles também são úteis para projetos que não lidam com dados corporativos. Por exemplo, um projeto que contém exclusivamente código nativo para executar operações de rede de baixo nível pode ser um bom candidato. Se um projeto fizer interface ampla com bibliotecas Android ou APIs do sistema, evite essas exclusões.
• excludeClasses Permite excluir uma lista de classes. Essas exclusões são úteis para classes que não manipulam ou apresentam dados corporativos. Por exemplo, telas iniciais e integração Activitysão bons candidatos. Uma classe não poderá ser excluída se qualquer uma de suas superclasses for processada.
• excludeVariants Permite a exclusão de variantes do projeto. Essas exclusões podem se referir a um nome de variante completo ou a um único sabor. Eles são especialmente úteis se você quiser criar um sabor não MAM do seu aplicativo. Por exemplo, se o seu aplicativo tiver tipos debug de build e release com sabores {noMAM, MAM} e {mock, production} você poderá 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']
}

Isso teria os seguintes efeitos:

• :product:FooLib não foi 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 é regravada 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 feitas. Para solicitar a geração deste relatório, especifique report = true no intunemam bloco de configuração. Se gerado, o relatório é gravado no diretório de outputs/logs compilação.

intunemam {
    report = true
}

Verificação

O plug-in de build pode executar mais verificações para procurar possíveis erros no processamento de classes. Essas verificações ajudam a proteger contra possíveis falhas de tempo de execução induzidas por plug-in.

Para solicitar que a verificação seja executada em seu build, especifique verify = true no bloco de intunemam configuração. Isso pode adicionar vários segundos ao tempo gasto pela tarefa do plug-in.

intunemam {
    verify = true
}

Geralmente, uma falha de verificação representa um bug no plug-in de compilação. Para obter assistência em caso de falha, encaminhe o problema para o suporte da Microsoft. Se você não tiver um contrato de suporte da Microsoft, abra um problema no GitHub.

Builds incrementais

Para habilitar o suporte para construção incremental, especifique incremental = true no bloco de intunemam configuração. Esse recurso aumenta o desempenho de build processando apenas os arquivos de entrada alterados. A configuração padrão para incremental é false.

intunemam {
    incremental = true
}

Configuração do Módulo de Recursos Dinâmicos

Os Módulos de Recursos Dinâmicos são compilados separadamente do projeto do aplicativo. Dessa forma, os módulos de recursos dinâmicos também precisam aplicar o plug-in de compilação do Gradle.

O plug-in do Gradle tem limitações técnicas nas APIs que usa. Devido a essas limitações, as classes de aplicativo precisam ser reprocessadas ao transformar classes de módulo de recursos dinâmicos. Para garantir que esse reprocessamento possa ser feito, configure todos os módulos de recursos com as mesmas configurações do aplicativo.

Por exemplo, se um aplicativo exclui uma classe, o módulo de recurso dinâmico também deve excluir essa classe.

Integração com os destinos MAUI do .NET

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

Os destinos são importados automaticamente para seu aplicativo em tempo de compilação quando o SDK do Aplicativo do Intune para .NET MAUI - pacote NuGet do Android é adicionado.

Integrando com a Ferramenta de Compilação de Linha de Comando

A ferramenta de build de linha de comando está disponível na BuildTool pasta do drop. Ele executa a mesma função que o plug-in do Gradle e os destinos do .NET detalhados acima. No entanto, a ferramenta de linha de comando pode ser integrada a sistemas de compilação personalizados. Como a ferramenta é mais genérica, ela é mais complexa de invocar. Use o plug-in do Gradle ou destinos do .NET sempre que possível.

Usando a ferramenta Command-Line

A ferramenta de linha de comando pode ser invocada usando os scripts auxiliares fornecidos localizados no BuildTool\bin diretório.

A ferramenta espera os seguintes parâmetros.

A opção opcional --processed é usada para habilitar builds incrementais. O conjunto de arquivos/diretórios listados aqui deve ser separado das listas input e classpath.

Exemplo Command-Line invocação da ferramenta

> 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

Isso teria os seguintes efeitos:

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

Configurando MAMApplication

Se o aplicativo criar uma subclasse de , o plug-in de build ou a ferramenta de linha de comando transformará a classe do android.app.Applicationaplicativo.

Se o aplicativo não tiver uma subclasse android.app.Application, você deverá definir "com.microsoft.intune.mam.client.app.MAMApplication" como o "android:name" atributo na tag do <application> AndroidManifest.xml.

Práticas recomendadas para Android

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

Depois de executar substituições automáticas, o SDK do Aplicativo do Intune ainda mantém o contrato fornecido pela API do Android. No entanto, as condições de falha podem ser disparadas com mais frequência como resultado da imposição da política. Estas práticas recomendadas do Android reduzem a probabilidade de falha:

• As funções do SDK do Android que podem retornar null agora têm uma probabilidade maior de retornar null. Certifique-se de que null as verificações protejam essas chamadas de função.
• Recursos que podem ser verificados, como clipboardManager.getPrimaryClipDescription(), devem ser verificados por meio de suas APIs de substituição de MAM, como MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Todas as funções derivadas devem chamar suas versões de superclasse.
• Evite o uso de qualquer API de forma ambígua. Por exemplo, usar Activity.startActivityForResult sem verificar o causa um requestCode comportamento estranho.

Serviços

A aplicação da política pode afetar as interações do Serviço Android. Métodos que estabelecem uma conexão de serviço associada, como Context.bindService podem falhar devido à imposição de política subjacente e Service.onBind podem resultar em ServiceConnection.onNullBinding ou ServiceConnection.onServiceDisconnected. A interação com um serviço associado estabelecido pode gerar um devido à imposição de SecurityException política no Binder.onTransact.

Os clientes de serviços associados são incentivados a marcar se há exceções geradas pelo serviço. Não deixe que exceções se propaguem para o restante do aplicativo cliente.

Critérios de Saída

Depois de configurar o plug-in de build ou integrar a ferramenta de linha de comando ao processo de build, valide se ela está sendo executada com êxito:

• Certifique-se de que seu build seja compilado e compilado com êxito.
• Configure o report sinalizador, abra o documento de relatório e confirme se as substituições de classe e método estão ocorrendo:
  • Se estiver usando o plug-in, siga as etapas em Relatórios.
  • Se estiver usando a ferramenta de linha de comando, inclua o --report sinalizador.
• Se estiver usando o plug-in, configure o verify sinalizador e certifique-se de que ele não produza erros. Consulte Verificação.
• Marque todas as exclusões (excludeProjects, excludeClassese excludeVariants) em build.gradle. Confirme se cada exclusão é necessária e não lida com dados protegidos. Historicamente, muitos erros de vazamento de dados ocorrem devido a exclusões excessivamente agressivas.
• Sem o Portal da Empresa do Intune instalado, inicie seu aplicativo compilado. Entre com um usuário do Microsoft Entra que não seja direcionado com a Política de Proteção do Aplicativo. Confirme se o aplicativo funciona conforme o esperado.
  • Saia e repita este teste com o Portal da Empresa do Intune instalado.

Perguntas frequentes

Meu aplicativo integrou anteriormente o SDK sem o plug-in de compilação; como posso usar o plug-in de compilação?

As versões mais antigas do SDK do Aplicativo do Intune não incluíam nenhuma maneira automatizada de executar substituições de classe e método. Os desenvolvedores precisavam executar essas substituições manualmente no código-fonte. Se o aplicativo for integrado dessa maneira, é seguro aplicar o plug-in de build ou a ferramenta de build de linha de comando. Você não precisa de nenhuma modificação de código-fonte. Seu projeto ainda deve listar o SDK do MAM como uma dependência.

Próximas etapas

Depois de concluir todos os Critérios de Saída, continue para o Estágio 4: Fundamentos de Integração MAM.