Compartilhar via

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

  • Artigo

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

Observação

Este guia está dividido em várias fases distintas. Comece por rever a Fase 1: Planear a Integração.

Fase 3: Introdução com MAM

Fase Goals

  • 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 da 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.
  • THIRDPARTYNOTICES.TXT: um aviso de atribuição que reconhece código de terceiros e/ou OSS que será compilado na sua aplicação.
  • Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: este 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 no 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 e 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 acima, integra automaticamente a configuração do SDK no passo ProGuard, para que os ficheiros de classe necessários sejam mantidos. Se tiver incluído corretamente 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 nuvem ou dispositivos, ou configuração MSAL, que tem de ser concluída antes de a sua 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.

Impacto na depuração

As ferramentas de compilação executam substituições após a compilação, o que irá alterar alguns nomes de métodos. Como resultado, a depuração de pontos de interrupção definidos nos nomes dos métodos pode ser afetada e não parar conforme esperado. Os pontos de interrupção do número de linha não são afetados.

MAM na Pilha

Uma vez que a integração do SDK da Aplicação Intune depende muito das substituições de classes e métodos, começará a ver mam os rastreios de pilha. Quando a sua aplicação não tem uma conta direcionada com políticas de proteção de aplicações, todo este código MAM está inativo: MAMActivity funcionará idêntico a Activity, onMAMCreate funcionará idêntico a onCreate, etc. 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 está a funcionar 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 opções acima, 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.

Observação

A partir do SDK da Aplicação 8.0 Intune, já não é possível processar bibliotecas seletivamente. Todas as bibliotecas são processadas.

Dependências

Observação

Tem de utilizar a versão 3.6.1 ou mais recente do plug-in do Android Gradle e a versão 5.6.4 ou mais recente do Gradle.

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 será adicionado nenhum código Javassist à sua aplicação.

Observação

As versões javassist podem não ser retrocompatíveis. Geralmente, deve utilizar a versão exata esperada pelo SDK da Aplicação Intune:

  • Intune SDK da Aplicação ≥ 10.0.0 requer Javassist 3.29.2-GA
  • Intune SDK da Aplicação ≥ 7.0.0 requer Javassist 3.27.0-GA
  • Intune SDK < da Aplicação 7.0.0 requer Javassist 3.22.0-GA

Além disso, ao consumir o SDK MAM 8.0.0+, tem de garantir que o seguinte está definido na configuração do Gradle:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Exclusões

Podem ser fornecidas configurações adicionais 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 e/ou 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, estas exclusões devem ser evitadas.
  • 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. Tenha em atenção que 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 o seguinte:
    • noMAM para excluir todas as variantes com o sabor noMAM ou
    • noMAMMockDebug para excluir apenas essa variante exata.

Cuidado

As exclusões não devem ser tomadas de ânimo leve. A aplicação incorreta de exclusões pode resultar em fugas de dados graves na sua aplicação. Valide sempre o impacto de qualquer exclusão que aplicar.

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 será escrito outputs/logs no diretório build.

intunemam {
    report = true
}

Verificação

O plug-in de compilação pode executar uma verificação adicional 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 foram 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.

Devido a limitações técnicas nas APIs utilizadas pelo plug-in do Gradle, as classes de aplicações têm de ser reprocessadas ao transformar classes dinâmicas de módulos de funcionalidades. Para garantir que isto pode ser feito, todos os módulos de funcionalidades devem ser configurados com as mesmas definições da aplicação para a qual foi concebido.

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 serão automaticamente importados 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 do Gradle/destinos.NET detalhados acima, mas pode ser integrado em sistemas de compilação personalizados. Como é mais genérico, é mais complexo invocar, pelo que os destinos de plug-in/.NET do Gradle devem ser utilizados 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.

Parâmetro Obrigatório Descrição
--input Sim Uma lista delimitada por ponto e vírgula de ficheiros jar e diretórios de ficheiros de classe a modificar. Isto deve incluir todos os jars/diretórios que pretende reescrever.
--output Sim Uma lista delimitada por ponto e vírgula de ficheiros jar e diretórios para armazenar as classes modificadas. Deve existir uma entrada de saída por entrada e devem ser listadas por ordem.
--classpath Sim O caminho de classe de compilação. Isto pode conter jars e diretórios de classe.
--processed Não Uma lista delimitada por ponto e vírgula de ficheiros jar e diretórios que contêm classes que já foram processadas por uma invocação anterior da ferramenta de compilação.
--excludeClasses Não Uma lista delimitada por ponto e vírgula que contém os nomes das classes que devem ser excluídas da reescrita.
--report Não Diretório para escrever um relatório HTML sobre classes modificadas. Se não for especificado, não é escrito nenhum relatório.

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.

Dica

Em sistemas semelhantes a Unix, o ponto e vírgula é um separador de comandos. Para evitar que a shell divida comandos, certifique-se de que escapa a cada ponto e vírgula com "" ou coloque o parâmetro completo entre aspas.

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

Aviso

Atualmente, a ferramenta de compilação não suporta ficheiros aar. Se o seu sistema de compilação ainda não extrair classes.jar ao lidar com ficheiros aar, terá de o fazer antes de invocar a ferramenta de compilação.

Definir MAMApplication

Se a sua aplicação criar uma subclasse de android.app.Application, a ferramenta de linha de comandos/plug-in de compilação transformará 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.

  • 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 reduzirão 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 o requestCode causará 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 fortemente encorajados a marcar para exceções emitidas pelo serviço em vez de permitir 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 executada 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, muitos erros de fuga de dados ocorreram 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 e 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 efetuar substituições de classes e métodos, e os programadores precisavam de realizar estas substituições manualmente no código fonte. Se a sua aplicação já tiver sido integrada desta forma, é seguro aplicar o plug-in de compilação (ou a ferramenta de compilação da linha de comandos) sem 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 Essentials.