SDK do Aplicativo do Intune para Android – MAM integration essentials

O SDK do aplicativo Microsoft Intune para Android permite que você incorpore políticas de proteção de aplicativo do Intune (também conhecidas como políticas de APP ou MAM) em seu aplicativo Java/Kotlin Android nativo. Um aplicativo gerenciado pelo Intune é integrado ao SDK do Aplicativo do Intune. Os administradores do Intune podem implantar facilmente políticas de proteção de aplicativo em seu aplicativo gerenciado pelo Intune quando o Intune gerencia ativamente o aplicativo.

Observação

Este guia é dividido em vários estágios distintos. Comece examinando a Fase 1: Planeje a Integração.

Estágio 4: MAM Integration Essentials

Goals de estágio

  • Habilitar o Modo Estrito do MAM.
  • Registre-se para notificações críticas do SDK.
  • Implemente e registre um retorno de chamada de autenticação para fornecer tokens Microsoft Entra do MSAL para o SDK.
  • Registre novas contas para o gerenciamento de MAM após a autenticação com o MSAL.
  • Cancelar o registro de contas no log-out para remover dados corporativos.
  • (Recomendado) Incorpore o registro em log do MAM em seu aplicativo.
  • (Recomendado) Saiba como usar a caixa de diálogo de diagnóstico do SDK.

Background

Agora que você tem o SDK do Aplicativo do Intune baixado, integrado ao seu build e executando com êxito substituições de classe e método, é hora de fazer as alterações de código essenciais para começar a impor configurações de política de proteção de aplicativo para contas protegidas por MAM.

Este estágio instruirá você sobre como conectar-se ao log do SDK, invocar uma caixa de diálogo diagnóstico, permitir que o Modo Rígido do MAM identifique possíveis bugs de integração, registre-se para notificações do SDK e, o mais importante, como registrar uma conta no MAM do Intune para começar a receber a política.

Modo Estrito do MAM

O Modo Rígido do MAM pode identificar possíveis bugs na integração do aplicativo ao SDK do Aplicativo do Intune. Esses bugs de integração podem resultar em falhas para aplicar corretamente a política de proteção de aplicativo e deixar os dados corporativos desprotegidos. Como resultado, o uso do Modo Estrito do MAM é necessário.

O Modo Estrito do MAM procura anomalias no uso de APIs de MAM do aplicativo e APIs de plataforma restritas ao MAM. Livremente padronizado após o StrictMode do Android, o Modo Rígido do MAM executa um conjunto predefinido de verificações que geram erros de runtime quando falham. O Modo Estrito do MAM não se destina a ficar habilitado em builds de produção; Em vez disso, use-o nos builds de desenvolvimento interno, depuração e/ou dogfood do seu aplicativo.

Para habilitar o Modo Estrito do MAM, chame

MAMStrictMode.enable();

inicialização antecipada do aplicativo (por exemplo, Application.onCreate).

Quando uma marcar do Modo Estrito do MAM falhar, tente determinar se é um problema real que pode ser corrigido em seu aplicativo ou um falso positivo. Se você acredita que é um falso positivo ou não tem certeza, informe a equipe do MAM do Intune. Isso nos permitirá concordar com a falsa determinação positiva e tentar melhorar a detecção de versões futuras. Para suprimir falsos positivos, desabilite o marcar de falha seguindo as instruções abaixo.

Manipulando violações

Quando um marcar falha, ele executa um MAMStrictViolationHandler. O manipulador padrão lança um Error, que deverá travar o aplicativo. Isso é para tornar as falhas o mais barulhentas possível e se encaixa com a intenção de que o modo rigoroso não deve ser habilitado em builds de produção.

Se seu aplicativo quiser lidar com violações de forma diferente, ele poderá fornecer seu próprio manipulador chamando:

MAMStrictMode.global().setHandler(handler);

onde handler implementa MAMStrictViolationHandler.

Supressão de verificações

Se um marcar falhar em uma situação em que seu aplicativo não está fazendo nada incorreto, denuncie-o conforme mencionado acima. Enquanto isso, talvez seja necessário desabilitar o marcar encontrar um falso positivo, pelo menos enquanto aguarda um SDK atualizado. O marcar que falhou será mostrado no erro gerado pelo manipulador padrão ou será passado para um manipulador personalizado se definido.

Embora as supressões possam ser feitas globalmente, é preferível desabilitar temporariamente por thread no site de chamada específico. Os exemplos a seguir mostram várias maneiras de desabilitar MAMStrictCheck.IDENTITY_NO_SUCH_FILE (gerados se for feita uma tentativa de proteger um arquivo que não existe).

supressão temporária Per-Thread

Este é o mecanismo de supressão preferencial.

try (StrictScopedDisable disable = MAMStrictMode.thread().disableScoped(MAMStrictCheck.IDENTITY_NO_SUCH_FILE)) {
    // Perform the operation which raised a violation here
}
// The check is no longer disabled once the block exits

supressão permanente Per-Thread

MAMStrictMode.thread().disable(MAMStrictCheck.IDENTITY_NO_SUCH_FILE);

Supressão global (em todo o processo)

MAMStrictMode.global().disable(MAMStrictCheck.IDENTITY_NO_SUCH_FILE);

Registrar-se para notificações do SDK

O SDK do Aplicativo do Intune emite muitos tipos diferentes de notificações para informar os aplicativos sobre operações de gerenciamento sensíveis ao tempo. Seu aplicativo pode se registrar e tomar medidas ao receber qualquer uma dessas notificações.

Por exemplo, sempre que um administrador de TI emite um comando de apagamento seletivo para um dispositivo, o serviço do Intune envia uma notificação para o SDK, que é passada para seu aplicativo como WIPE_USER_DATA. Seu aplicativo pode escutar essa notificação e controlar quais dados foram apagados; ou pode contar com o comportamento padrão de apagamento do SDK.

Muitas das notificações são opcionais. Dependendo dos recursos do SDK que seu aplicativo usa, algumas notificações podem ser necessárias. Consulte Registrar para Notificações do SDK no Estágio 7: Recursos de Participação do Aplicativo para obter detalhes sobre como se registrar para notificações, quais notificações o SDK fornece e como lidar com tipos de notificação específicos.

Registrar-se para a Política de Proteção de Aplicativos

Quando os administradores criam Políticas de Proteção de Aplicativo, eles direcionam essas políticas para contas específicas em sua organização. No cliente, o SDK precisa saber qual conta está usando o aplicativo para que ele possa recuperar a política dessa conta e impor as configurações adequadamente. Seu aplicativo é responsável por fornecer ao SDK informações dessa conta. Esse processo é chamado de registro.

Sempre que seu aplicativo adiciona uma nova conta, ele deve registrar a conta com o SDK, mesmo que outras contas já estejam registradas. Seu aplicativo pode registrar várias contas. No entanto, atualmente, apenas uma conta pode ser registrada ou ter a política de proteção de aplicativo aplicada. No Android, essa limitação de conta gerenciada única é em todo o dispositivo.

Registro vs Registro

O registro é o processo em que seu aplicativo informa ao SDK que uma nova conta está em uso. O SDK contém funções que seu aplicativo deve chamar para registrar e cancelar o registro de contas.

O registro é o processo em que o SDK registra a conta registrada com o serviço do Intune para que ela possa aplicar a política da conta. Seu aplicativo não precisa chamar nenhuma função para registro. O SDK lida totalmente com o registro depois que uma conta é registrada.

Se uma conta já estiver registrada para seu aplicativo, quando registrar outra conta, mesmo que essa conta seja direcionada às Políticas de Proteção de Aplicativo, essa segunda conta não será registrada e a política não será aplicada.

Observação

O termo "registro" também pode se referir ao registro de MDM em todo o dispositivo Saiba mais no apêndice no registro de MDM e MAM.

Implementando o registro

Cuidado

Se seu aplicativo não integrar o MSAL (altamente recomendado), consulte Registro Padrão no Apêndice em vez de continuar esta seção.

Seu aplicativo deve fazer três alterações de código para registrar com êxito uma conta:

  1. O aplicativo deve implementar e registrar uma instância da interface MAMServiceAuthenticationCallback . A instância de retorno de chamada deve ser registrada no onCreate() método (ou onMAMCreate()) da subclasse de aplicativo.

  2. Quando uma conta é criada e o usuário entra com êxito com o MSAL, o aplicativo deve chamar registerAccountForMAM.

  3. Quando uma conta é removida, o aplicativo deve chamar unregisterAccountForMAM para remover a conta do gerenciamento do Intune.

    Cuidado

    A chamada pode iniciar um apagamento para remover completamente os dados corporativos da conta.

Todas as APIs de autenticação e registro necessárias podem ser encontradas na interface MAMEnrollmentManager . Uma referência ao pode ser obtida da MAMEnrollmentManager seguinte maneira:

MAMEnrollmentManager mgr = MAMComponents.get(MAMEnrollmentManager.class);

// make use of mgr

A MAMEnrollmentManager instância retornada é garantida para não ser nula. Os métodos de API se enquadram em duas categorias: autenticação e registro de conta.

MAMEnrollmentManager e Authentication

O SDK se comunica com frequência com o serviço do Intune: para registrar contas registradas, para obter atualizações nas configurações da Política de Proteção de Aplicativo e para obter ações de administrador pendentes, como limpar seletivamente dados protegidos dentro de seu aplicativo. Para se comunicar com êxito com o serviço do Intune, o SDK requer novos tokens de acesso de aplicativos que integraram o MSAL.

Se o SDK não conseguir recuperar um novo token, ele não poderá se comunicar com o serviço do Intune, o que pode atrasar a recuperação e a aplicação de novas configurações de política ou ações de administrador. É fundamental que seu aplicativo conclua essas etapas para garantir a imposição contínua da política.

No Estágio 2, você integrou o MSAL ao seu aplicativo para autenticação e aquisição de tokens de acesso. Aqui, você implementará um retorno de chamada de autenticação para permitir que o SDK solicite tokens necessários.

MAMEnrollmentManager tem os seguintes métodos de autenticação:

interface MAMServiceAuthenticationCallback {
    String acquireToken(String upn, String aadId, String resourceId);
}
interface MAMServiceAuthenticationCallbackExtended extends MAMServiceAuthenticationCallback {
    String acquireToken(String upn, String aadId, String tenantId, String authority, String resourceId);
}
void registerAuthenticationCallback(MAMServiceAuthenticationCallback callback);
void updateToken(String upn, String aadId, String resourceId, String token);
  1. O aplicativo deve implementar a interface MAMServiceAuthenticationCallback ou a MAMServiceAuthenticationCallbackExtended interface para permitir que o SDK solicite um token Microsoft Entra para a conta e a ID de recurso fornecidas. A instância de retorno de chamada deve ser fornecida ao MAMEnrollmentManager chamando seu método registerAuthenticationCallback . Um token pode ser necessário no início do ciclo de vida do aplicativo para tentativas de registro ou atualização de política de proteção de aplicativo marcar-ins, portanto, o retorno de chamada deve ser registrado no onCreate() método (ou onMAMCreate()) da subclasse do Application aplicativo.

  2. O acquireToken método deve adquirir o token de acesso para a ID de recurso solicitada para a conta determinada. Se ele não conseguir adquirir o token solicitado, ele deverá retornar nulo.

    Dica

    Verifique se seu aplicativo utiliza o resourceId e os aadId parâmetros passados para para acquireToken() que o token correto seja adquirido. O resourceId deve ser usado para gerar os escopos adequados e o aadId deve ser usado para transmitir a conta correta. Se o aplicativo precisar da Autoridade Microsoft Entra para adquirir o token corretamente, implemente a MAMServiceAuthenticationCallbackExtended interface.

    class MAMAuthCallback implements MAMServiceAuthenticationCallback {
        public String acquireToken(String upn, String aadId, String resourceId) {
            final String[] scopes = {resourceId + "/.default"};
    
            final IAccount account = getAccount(aadId);
            if (account == null) {
                callback.onError(
                        new MsalUiRequiredException(MsalUiRequiredException.NO_ACCOUNT_FOUND, "no account found for " + aadId));
                return;
            }
    
            AcquireTokenSilentParameters params =
                new AcquireTokenSilentParameters.Builder()
                        .forAccount(account)
                        .fromAuthority(account.getAuthority())
                        .withScopes(Arrays.asList(scopes))
                        .withCallback(callback)
                        .build();
    
            return mMsalClientApplication.acquireTokenSilent(params);
        }
    
        private static IAccount getAccount(String aadId) throws InterruptedException, MsalException {
          IAccount account = null;
    
          if (mMsalClientApplication instanceof IMultipleAccountPublicClientApplication) {
              IMultipleAccountPublicClientApplication multiAccountPCA =
                      (IMultipleAccountPublicClientApplication) mMsalClientApplication;
    
              account = multiAccountPCA.getAccount(aadId);
          } else {
              ISingleAccountPublicClientApplication singleAccountPCA =
                      (ISingleAccountPublicClientApplication) mMsalClientApplication;
    
              ICurrentAccountResult accountResult = singleAccountPCA.getCurrentAccount();
              if (accountResult != null) {
                  account = accountResult.getCurrentAccount();
                  // make sure this is the correct user
                  if (account != null && !account.getId().equals(aadId))
                      account = null;
              }
          }
          return account;
      }
    }
    
  3. Caso o aplicativo não possa fornecer um token quando o SDK chamar acquireToken() -- por exemplo, se a autenticação silenciosa falhar e for um momento inconveniente para mostrar uma interface do usuário -- o aplicativo pode fornecer um token posteriormente chamando o método updateToken . O mesmo UPN, Microsoft Entra ID e ID de recurso que foram solicitados pela chamada anterior devem acquireToken() ser passados para updateToken(), juntamente com o token que foi finalmente adquirido. O aplicativo deve chamar esse método o mais rápido possível depois de retornar nulo do retorno de chamada fornecido.

    Aviso

    Não chame updateToken() de dentro de sua implementação de acquireToken(). updateToken() deve ser usado no caso em que acquireToken() não é possível adquirir um token.

    Observação

    O SDK chamará acquireToken() periodicamente para obter o token, portanto, a chamada updateToken() não é estritamente necessária. No entanto, é altamente recomendável, pois pode ajudar os registros e a política de proteção de aplicativo marcar-ins concluídas em tempo hábil.

Notas de implementação de autenticação

  • Os aplicativos são incentivados a adquirir tokens Microsoft Entra antes de chamar registerAccountForMAM. Depois de registrar uma conta, os aplicativos receberão um retorno de chamada para o método registrado MAMServiceAuthenticationCallbackacquireToken() em um thread diferente. Fornecer um token válido nesse retorno de chamada permite que o registro prossiga. O aplicativo receberá o resultado do registro por meio de notificação.

  • Se o aplicativo não retornar um token de Microsoft Entra válido, o resultado final da tentativa de registro será AUTHORIZATION_NEEDED. Se o aplicativo receber esse Resultado por meio de notificação, é altamente recomendável agilizar o processo de registro adquirindo o token para a conta e o recurso solicitado anteriormente de acquireToken e chamando o método updateToken para iniciar o processo de registro novamente.

  • O registro MAMServiceAuthenticationCallback do aplicativo também será chamado para adquirir um token para marcar de atualização de política de proteção de aplicativo periódica. Se o aplicativo não puder fornecer um token quando solicitado, ele não receberá uma notificação, mas tentará adquirir um token e chamar updateToken() no próximo momento conveniente para agilizar o processo de marcar. Se um token não for fornecido, o retorno de chamada ainda poderá ser chamado na próxima tentativa de marcar.

  • O suporte para nuvens soberanas requer o fornecimento da autoridade.

  • Se MAMServiceAuthenticationCallbackExtended a interface for implementada, o método MAMServiceAuthenticationCallback herdado acquireToken() não precisará ser implementado, pois a MAMServiceAuthenticationCallbackExtended interface fornece uma implementação padrão.

MAMEnrollmentManager e Registro

Sempre que o aplicativo adiciona uma conta, ele deve registrar a conta com o SDK. Da mesma forma, sempre que o aplicativo remove uma conta, ele deve cancelar o registro dessa conta para indicar que o aplicativo não deve mais aplicar a política para essa conta. Se a conta foi registrada no serviço MAM, a conta será desativada e o aplicativo será apagado.

MAMEnrollmentManager tem os seguintes métodos de registro de conta:

void registerAccountForMAM(String upn, String aadId, String tenantId);
void registerAccountForMAM(String upn, String aadId, String tenantId, String authority);
void unregisterAccountForMAM(String upn, String aadId);
Result getRegisteredAccountStatus(String upn, String aadId);
  1. Para registrar uma conta para gerenciamento, o aplicativo deve chamar registerAccountForMAM(). Uma conta é identificada por sua UPN e sua ID de usuário Microsoft Entra. A ID do locatário também é necessária para associar dados de registro ao locatário Microsoft Entra da conta. A autoridade da conta também pode ser fornecida para permitir o registro em nuvens soberanas específicas; para obter mais informações, consulte Registro de Nuvem Soberana. O SDK pode tentar registrar o aplicativo para a conta determinada no serviço MAM; se o registro falhar, ele repetirá periodicamente o registro até que o registro seja bem-sucedido ou a conta não seja registrada. O período de repetição normalmente será de 12 a 24 horas. O SDK fornece o status de tentativas de registro de forma assíncrona por meio de notificações.

  2. A melhor hora para chamar registerAccountForMAM é depois que o usuário entrou no aplicativo e é autenticado com êxito usando o MSAL. A ID do usuário Microsoft Entra da conta e a ID do locatário são retornadas da chamada de autenticação MSAL como parte do IAccount relacionado ao IAuthenticationResult.

    • A conta vem do IAuthenticationResult.getAccount() método e contém as informações pertinentes da conta.
    • A ID do AAD vem do IAccount.getId() método.
    • A ID do locatário vem do IAccount.getTenantId() método.
    • A autoridade vem do IAccount.getAuthority() método.
  3. Para cancelar o registro de uma conta do gerenciamento do Intune, o aplicativo deve chamar unregisterAccountForMAM(). Se a conta tiver sido registrada com êxito e for gerenciada, o SDK desativará a conta e apagará seus dados. As novas tentativas de registro periódica para a conta serão interrompidas. O SDK fornece o status de solicitações de não registro de forma assíncrona por meio de notificação.

Notas de Implementação de Registro

  • Os métodos de registro são idempotentes. Por exemplo, registerAccountForMAM só registrará uma conta e tentará registrar o aplicativo se a conta ainda não estiver registrada, e unregisterAccountForMAM só cancelará o registro de uma conta se ela estiver registrada no momento. Chamadas subsequentes não são ops, portanto, não há nenhum dano em chamar esses métodos mais de uma vez.

  • Não há garantia de que cada chamada de registro/cancelamento de registro tenha uma notificação de resultado correspondente. Por exemplo, se registerAccountForMAM() for chamado para uma conta que já está registrada, a notificação poderá não ser enviada novamente para essa identidade. Como alternativa, o SDK pode enviar notificações mesmo quando seu aplicativo não chamou esses métodos, já que o SDK pode tentar periodicamente registros em segundo plano, e os cancelamentos podem ser disparados por solicitações de apagamento recebidas do serviço do Intune.

  • Os métodos de registro podem ser chamados para qualquer número de contas diferentes, mas atualmente apenas uma conta pode ser registrada com êxito. Se várias contas licenciadas para o Intune e direcionadas à política de proteção de aplicativo forem registradas ao mesmo tempo ou próximas, não haverá garantia de qual delas vencerá a corrida.

  • Você pode consultar o MAMEnrollmentManager para ver se uma determinada conta está registrada e obter seu status atual usando o método getRegisteredAccountStatus. Se a conta fornecida não estiver registrada, esse método retornará nulo. Se a conta for registrada, esse método retornará o status da conta como um dos membros da enumeração MAMEnrollmentManager.Result.

Registro de Nuvem Soberana

O Azure dá suporte a várias nuvens fisicamente isoladas, conhecidas como Nuvens Soberanas ou Nacionais. Se seu aplicativo estiver ciente da nuvem soberana, ele deverá fornecer o authority parâmetro para registerAccountForMAM().

Diretrizes do MSAL

Para MSAL, defina multiple_clouds_supported como true no arquivo de configuração MSAL.

{
  "multiple_clouds_supported": true,
}

Códigos de resultado e status de registro

Quando uma conta é registrada pela primeira vez, ela começa no PENDING estado, indicando que a tentativa inicial de registro do serviço MAM está incompleta. Após a conclusão da tentativa de registro, uma notificação será enviada com um dos códigos De resultado na tabela abaixo. Além disso, o método getRegisteredAccountStatus retornará o status da conta para que o aplicativo sempre possa determinar se essa conta tem políticas de proteção de aplicativo impostas. Se a tentativa de registro falhar, o status da conta poderá ser alterado ao longo do tempo à medida que o SDK tenta novamente o registro em segundo plano.

Código de resultado Explicação
AUTHORIZATION_NEEDED Esse resultado indica que um token não foi fornecido pela instância MAMServiceAuthenticationCallback registrada do aplicativo ou o token fornecido era inválido. O aplicativo deve adquirir um token válido e chamar updateToken , se possível.
NOT_LICENSED A conta não está licenciada para o Intune ou a tentativa de entrar em contato com o serviço MAM do Intune falhou. O aplicativo deve continuar em um estado não gerenciado (normal) e o usuário não deve ser bloqueado. Os registros serão julgados periodicamente no caso de a conta se tornar licenciada no futuro.
ENROLLMENT_SUCCEEDED A tentativa de registro foi bem-sucedida ou a conta já está registrada. No caso de um registro bem-sucedido, uma notificação de atualização de política será enviada antes desta notificação. O acesso aos dados corporativos deve ser permitido.
ENROLLMENT_FAILED A tentativa de registro falhou. Mais detalhes podem ser encontrados nos logs do dispositivo. O aplicativo não deve permitir acesso a dados corporativos nesse estado, pois foi determinado anteriormente que a conta está licenciada para o Intune. Todos os aplicativos devem garantir que o acesso a dados corporativos não seja autorizado até ENROLLMENT_SUCCEEDED que seja obtido pelo seu aplicativo.
WRONG_USER Apenas uma conta por dispositivo pode registrar um aplicativo com o serviço MAM. Esse resultado indica que a conta para a qual esse resultado foi entregue (a segunda conta) é direcionada à política de MAM, mas uma conta diferente já está registrada. Como a política MAM não pode ser imposta para a segunda conta, seu aplicativo não deve permitir o acesso aos dados dessa conta (possivelmente removendo a conta do aplicativo) a menos que o registro dessa conta seja bem-sucedido posteriormente. Simultaneamente à entrega desse WRONG_USER resultado, o MAM solicitará a opção de remover a conta existente. Se o usuário humano responder na afirmativa, será realmente possível registrar a segunda conta pouco tempo depois. Enquanto a segunda conta permanecer registrada, o MAM tentará novamente o registro periodicamente.
UNENROLLMENT_SUCCEEDED O cancelamento foi bem-sucedido.
UNENROLLMENT_FAILED A solicitação de cancelamento falhou. Mais detalhes podem ser encontrados nos logs do dispositivo. Em geral, isso não ocorrerá desde que o aplicativo passe um UPN válido (nem nulo nem vazio). Não há correção direta e confiável que o aplicativo possa levar. Se esse valor for recebido ao cancelar o registro de um UPN válido, informe como um bug para a equipe do MAM do Intune.
PENDING A tentativa inicial de registro da conta está em andamento. O aplicativo pode bloquear o acesso a dados corporativos até que o resultado do registro seja conhecido, mas não é necessário fazê-lo.
COMPANY_PORTAL_REQUIRED A conta é licenciada para o Intune, mas o aplicativo não pode ser registrado até que o aplicativo Portal da Empresa seja instalado no dispositivo. O SDK do Aplicativo do Intune tentará bloquear o acesso ao aplicativo para a conta determinada e direcioná-los para instalar o aplicativo Portal da Empresa. Ao enviar essa notificação para o aplicativo, o SDK do Aplicativo do Intune mostrará uma interface do usuário não desbloqueada em cima da Atividade atual se a Atividade estiver atualmente visível para o usuário ou a próxima vez onResume for chamada. Se o usuário cancelar essa interface do usuário não desbloqueada, o SDK do Aplicativo do Intune mostrará uma interface do usuário de bloqueio na próxima vez onCreate é chamada para uma Atividade e a identidade atual é gerenciada (confira abaixo para obter detalhes sobre solução de problemas).

O registro em log deve ser inicializado mais cedo para obter o maior valor dos dados registrados. Application.onMAMCreate() normalmente é o melhor lugar para inicializar o registro em log.

Para receber logs de MAM em seu aplicativo, crie um Manipulador Java e adicione-o ao MAMLogHandlerWrapper. Isso invocará publish() no manipulador de aplicativos para cada mensagem de log.

/**
 * Global log handler that enables fine grained PII filtering within MAM logs.  
 * To start using this you should build your own log handler and add it via
 * MAMComponents.get(MAMLogHandlerWrapper.class).addHandler(myHandler, false);  
 * You may also remove the handler entirely via
 * MAMComponents.get(MAMLogHandlerWrapper.class).removeHandler(myHandler);
 */
public interface MAMLogHandlerWrapper {
    /**
     * Add a handler, PII can be toggled.
     * @param handler handler to add.
     * @param wantsPII if PII is desired in the logs.    
     */
    void addHandler(final Handler handler, final boolean wantsPII);

    /**
     * Remove a handler.
     * @param handler handler to remove.
     */
    void removeHandler(final Handler handler);
}

Observação

O PII significa "informações pessoalmente identificáveis" e pode incluir dados como nomes de usuário e UPNs. Você é fortemente incentivado a excluir essas informações pessoais em seus próprios logs de produção. Consulte a Política de Privacidade da Microsoft para obter mais detalhes.

O aplicativo Portal da Empresa do Intune tem várias opções para coletar informações de diagnóstico. O Portal da Empresa inclui a interface do usuário que:

  • Permite que os usuários finais reúnam Portal da Empresa logs.
  • Exibe metadados de dispositivo e conta.
  • Inclui informações por aplicativo sobre a política de MAM atual.

Informações da interface do usuário de diagnóstico do Intune

Para obter uma explicação detalhada dos dados incluídos nos logs de Portal da Empresa e na interface do usuário diagnóstico, consulte Noções básicas sobre Portal da Empresa logs no Apêndice.

Dica

Se você estiver testando com uma conta que deve ter a política MAM aplicada, mas o diagnóstico não exibir nenhuma política para o nome do pacote do aplicativo, consulte a seção Solução de problemas abaixo.

Os aplicativos podem iniciar esse diagnóstico interface do usuário invocando MAMPolicyManager.showDiagnostics(context). Os usuários finais também podem iniciar o console de diagnóstico do Portal da Empresa por meio do Microsoft Edge, inserindo na barra de about:intunehelp endereços. Esse é um recurso opcional que pode ajudar na depuração.

Essas informações diagnóstico só estarão disponíveis quando o Portal da Empresa estiver instalado no dispositivo. Uma caixa de diálogo de aviso será exibida sempre que showDiagnostics for chamada sem o Portal da Empresa instalado.

Critérios de saída

Neste ponto da integração, seu aplicativo agora pode receber e impor a Política de Proteção de Aplicativo. Execute os testes a seguir para validar a integração.

Primeiro teste de aplicativo de política

Execute o teste a seguir primeiro para se familiarizar com a experiência completa do usuário final do aplicativo de política em seu aplicativo:

  1. Crie uma Política de Proteção de Aplicativo Android no centro de administração do Microsoft Intune (consulte Criando uma política de proteção de aplicativo Android de teste no Estágio 1 para obter detalhes). Para este teste, configure a política:
    • Em Proteção de Dados, defina "Captura de tela e Google Assistente" como "Bloquear".
    • Em Requisitos de Acesso, deixe as configurações padrão. Notavelmente, "PIN for Access" deve ser "Obrigatório".
  2. Verifique se a Política de Proteção de Aplicativo está direcionada ao seu aplicativo. É provável que você precise adicionar manualmente o nome do pacote no assistente de criação de política.
  3. Atribua a Política de Proteção de Aplicativo a um grupo de usuários que contém sua conta de teste.
  4. Em um dispositivo Android de teste, desinstale outros aplicativos integrados ao SDK, como Microsoft Outlook, Teams, OneDrive e Office. Também desinstale o aplicativo Portal da Empresa do Intune e o aplicativo Microsoft Authenticator.
    • Dica

      A desinstalação de outros aplicativos integrados ao SDK ajuda a garantir que você esteja testando exclusivamente a integração do seu próprio aplicativo.

  5. Instale seu aplicativo.
  6. Faça logon no aplicativo com sua conta de teste direcionada à Política de Proteção de Aplicativo.
  7. Confirme se você foi solicitado a instalar o Portal da Empresa do Intune do Google Play.
    • Observação

      Se o dispositivo de teste não tiver o aplicativo Google Play Store, confirme se você será solicitado a instalar o Portal da Empresa do Intune de outra loja de aplicativos ou de um site da Microsoft.

  8. Instale o Portal da Empresa. Você não precisa iniciar o Portal da Empresa ou fazer logon no Portal da Empresa.
  9. Retorne ao aplicativo e faça logon novamente, se necessário.
  10. Confirme se você foi solicitado com uma tela Obter Acesso. Isso indica que o SDK recuperou com êxito a política para essa conta.
  11. Você deve ser solicitado a definir um PIN de aplicativo. Criar um PIN.
  12. Navegue pelo aplicativo e tente fazer capturas de tela. Dado que o SDK tem política, isso deve ser constantemente bloqueado em qualquer tela.
  13. Registre a conta gerenciada fora do aplicativo.
  14. Se possível sem fazer logon, navegue pelo aplicativo e tente fazer capturas de tela. Agora que a conta foi removida, isso não deve ser bloqueado.

Este é um teste mínimo para confirmar que seu aplicativo registrou corretamente a conta, registrou o retorno de chamada de autenticação e não registrou a conta. Execute os testes a seguir para validar mais detalhadamente como outras configurações da Política de Proteção de Aplicativo modificam o comportamento do seu aplicativo.

Testes de Proteção de Dados

Os testes a seguir abrangem configurações específicas de proteção de dados configuradas na Política de Proteção de Aplicativo. Quando você altera as configurações da Política de Proteção de Aplicativo no centro de administração Microsoft Intune, o cliente não será atualizado imediatamente. Consulte Testar rapidamente com a política de alteração para obter dicas sobre como acelerar os testes.

Para estes testes:

  1. Instale seu aplicativo.
  2. Instale o Portal da Empresa do Intune.
  3. Instale outro aplicativo gerenciado, direcionado com a mesma política que seu aplicativo, que pode copiar e colar dados (como o Microsoft Office).
  4. Instale (ou reutilize) qualquer aplicativo não gerenciado que possa copiar e colar dados.
  5. Faça logon no aplicativo com a conta gerenciada de teste.
  6. Faça logon no outro aplicativo gerenciado com a conta de teste gerenciada.
Cenário Configuração da Política de Proteção de Aplicativo Etapas de teste
Captura de tela "Captura de tela e Google Assistente" definido como "Bloquear" 1. Navegue até todas as páginas do aplicativo.
2. Tente fazer uma captura de tela em cada página.
3. Confirme se as capturas de tela estão bloqueadas ou a imagem salva está totalmente em branco.
Copiar texto "Restringir o corte, copiar e colar entre outros aplicativos" definido como "Aplicativos gerenciados por políticas" 0. Se o aplicativo não tiver texto para copiar, pule.
1. Navegue até todas as páginas em seu aplicativo que tenham texto copiado.
2. Copiar texto.
3. Alterne para o aplicativo não gerenciado.
4. Tente colar no aplicativo não gerenciado.
5. Confirme se a pasta está bloqueada.
6. Navegue até o outro aplicativo gerenciado.
7. Tente colar no aplicativo gerenciado.
8. Confirme se a pasta é permitida.
Colar texto "Restringir o corte, copiar e colar entre outros aplicativos" definido como "Aplicativos gerenciados por políticas" 0. Se o aplicativo não tiver nenhuma entrada de texto para colar, pule.
1. Alterne para o aplicativo não gerenciado.
2. Copiar texto do aplicativo não gerenciado.
3. Navegue até todas as páginas do aplicativo que têm entradas de texto.
5. Tente colar do aplicativo não gerenciado.
5. Confirme se a pasta está bloqueada.
6. Alterne para o outro aplicativo gerenciado.
7. Copiar texto do outro aplicativo gerenciado.
7. Navegue até todas as páginas do aplicativo que têm entradas de texto.
8. Tente colar do outro aplicativo gerenciado.
9. Confirme se a pasta é permitida.
Impressão "Imprimir dados da Organização" definido como "Bloquear" 0. Se o aplicativo não tiver páginas ou documentos que possam ser impressos, pule.
1. Navegue até todas as páginas do aplicativo que invocam a função de impressão do Android.
2. Tente imprimir de cada página.
3. Confirme se a impressão está bloqueada.
Navegador gerenciado "Restringir a transferência de conteúdo da Web com outros aplicativos" definido como "Microsoft Edge" 0. Se o aplicativo não renderizar weblinks, ignore.
1. Navegue até todas as páginas do seu aplicativo que podem exibir weblinks ou ter entradas de texto que renderizam em weblinks clicáveis.
2. Para cada página, selecione o weblink.
3. Confirme se você foi solicitado a instalar o Microsoft Edge e o weblink não é aberto em outro navegador.
Teclado restrito "Teclados aprovados" definido como "Obrigatório"
"Selecionar teclados para aprovar" definido como apenas um pacote de teclado que seu dispositivo não instalou no momento
0. Se o aplicativo não tiver nenhuma entrada de texto, pule.
1. Navegue até todas as páginas do aplicativo que têm entradas de texto.
2. Selecione a entrada de texto para criar o teclado do dispositivo.
3. Confirme se você foi solicitado a instalar o teclado aprovado configurado e o teclado do dispositivo atual não é aberto.

Testes de transferência de dados

As configurações de transferência de dados são um subconjunto de recursos de proteção de dados da Política de Proteção de Aplicativo que controlam a entrada e saída de dados de aplicativos gerenciados. A maioria dos aplicativos que dão suporte ao envio de dados ou ao recebimento de dados de outros aplicativos também tem a capacidade de salvar dados e abrir dados do armazenamento local ou na nuvem. Se seu aplicativo tiver esses recursos, você precisará implementar suporte adicional. Consulte Política para limitar a transferência de dados entre aplicativos e locais de armazenamento em nuvem ou dispositivo para obter detalhes.

Seu aplicativo pode importar ativamente dados de outros aplicativos, como o Microsoft Outlook anexando um arquivo do Microsoft OneDrive. Seu aplicativo também pode receber passivamente dados de outros aplicativos, como o Microsoft Office abrindo um documento de um anexo do Microsoft Outlook. A configuração da política de proteção de aplicativo de recebimento abrange ambos os cenários.

Para estes testes:

  1. Instale seu aplicativo.
  2. Instale o Portal da Empresa do Intune.
  3. Instale outro aplicativo gerenciado, direcionado com a mesma política que seu aplicativo, que pode enviar e receber dados (como o Microsoft Outlook).
  4. Instale (ou reutilize) qualquer aplicativo não gerenciado que possa enviar e receber dados.
  5. Faça logon no aplicativo com a conta gerenciada de teste.
  6. Faça logon no outro aplicativo gerenciado com a conta de teste gerenciada.
Cenário Configuração da Política de Proteção de Aplicativo Etapas de teste
Enviar dados para outros aplicativos "Enviar dados da organização para outros aplicativos" definido como "Aplicativos gerenciados por política" 0. Se seu aplicativo não puder enviar dados para outros aplicativos, ignore.
1. Navegue até onde seu aplicativo pode enviar dados.
2. Tente enviar dados.
3. Confirme se você está limitado a enviar dados apenas para outros aplicativos gerenciados. Você deve ver um seletor de aplicativos com apenas aplicativos gerenciados.
Importação de dados de outros aplicativos "Receber dados de outros aplicativos" definido como "Aplicativos gerenciados por políticas" 0. Se seu aplicativo não puder importar dados de outros aplicativos, ignore.
1. Navegue até onde seu aplicativo pode importar dados de outros aplicativos.
2. Tente importar dados.
3. Confirme se você está limitado a importar dados apenas de outros aplicativos gerenciados. Você deve ver um seletor de aplicativos com apenas aplicativos gerenciados.
Recebimento de dados de aplicativo não gerenciado "Receber dados de outros aplicativos" definido como "Aplicativos gerenciados por políticas" 0. Se seu aplicativo não puder receber dados de outros aplicativos, ignore.
1. Alterne para o aplicativo não gerenciado.
2. Navegue até onde pode enviar dados.
3. Tente enviar dados do aplicativo não gerenciado para seu aplicativo.
4. Confirme se seu aplicativo não é capaz de receber dados do aplicativo não gerenciado.
Recebimento de dados do aplicativo gerenciado "Receber dados de outros aplicativos" definido como "Aplicativos gerenciados por políticas" 0. Se seu aplicativo não puder receber dados de outros aplicativos, ignore.
1. Alternar para o outro aplicativo gerenciado.
2. Navegue até onde pode enviar dados.
3. Tente enviar dados do outro aplicativo gerenciado para seu aplicativo.
4. Confirme se seu aplicativo é capaz de receber dados do outro aplicativo gerenciado.

Outras configurações de proteção de dados

As seguintes configurações de proteção de dados não serão impostas até que seu aplicativo faça alterações adicionais. Você não precisa testar essas configurações nesta fase. Confira Estágio 7: Recursos de Participação do Aplicativo para obter mais detalhes.

Cenário Configuração da Política de Proteção de Aplicativo Deve implementar o suporte se...
Salvar cópias de dados Salvar cópias de dados da organização Seu aplicativo pode salvar dados no armazenamento local ou na nuvem.
Abrir dados do armazenamento Abrir dados em documentos da organização Seu aplicativo pode abrir dados do armazenamento local ou na nuvem.
Conteúdo de notificação gerenciada Notificações de dados da organização Seu aplicativo inclui dados do usuário dentro de notificações.
Backup e restauração Backup de dados da organização para serviços de backup do Android Seu aplicativo compartilha dados do usuário com o recurso de backup do Android.

Testes de inicialização condicional

As configurações de inicialização condicional são um subconjunto de recursos da Política de Proteção de Aplicativo que restringem o acesso ao aplicativo com base em critérios configuráveis em todo o dispositivo ou específicos do aplicativo. Essas configurações incluem condições (como "versão mínima do sistema operacional") e ações (como "acesso de bloco"). As ações de inicialização condicional podem ser:

  • Aviso: o usuário final verá uma caixa de diálogo de aviso quando seu dispositivo ou aplicativo falhar nos critérios. Eles ainda terão acesso a todos os dados do aplicativo.
  • Bloquear o acesso: o usuário final verá uma caixa de diálogo de aviso quando seu dispositivo ou aplicativo falhar nos critérios. Eles não poderão inserir o aplicativo e acessar dados do aplicativo até que atendam aos critérios ou removam a conta gerenciada do aplicativo.
  • Apagar dados: todos os dados corporativos associados à conta gerenciada serão apagados quando o dispositivo ou o aplicativo falhar nos critérios. O usuário não terá a oportunidade de atender aos critérios antes que os dados sejam removidos.

Algumas configurações de inicialização condicional podem ser configuradas com vários valores e ações. Por exemplo:

  • Versão mínima do sistema operacional, valor de "10.0", ação definida como "Avisar".
  • Versão mínima do sistema operacional, valor de "9.0", ação definida como "Bloquear acesso"
  • Versão mínima do sistema operacional, valor de "8.0", ação definida como "Apagar dados".

Ao concluir as etapas de integração nesta fase, seu aplicativo agora dá suporte a todos os recursos de inicialização condicional. Familiarize-se com a funcionalidade de inicialização condicional alterando itens de política de modo que seu dispositivo de teste:

  • Passa todas as configurações de inicialização condicional configuradas.
  • Falha em uma configuração de inicialização condicional configurada definida como a ação "Avisar".
  • Falha em uma configuração de inicialização condicional configurada definida como a ação "Bloquear acesso".
  • Falha em uma configuração de inicialização condicional configurada definida como a ação "Apagar dados".

Solução de problemas

Solução de problemas do primeiro teste de aplicativo de política

Seguindo as etapas do Primeiro Teste de Aplicativo de Política acima, você pode encontrar os seguintes comportamentos inesperados:

Depois de fazer logon com uma conta gerenciada, não sou solicitado a instalar o Portal da Empresa (etapa 7)

Primeiro, visite o centro de administração do Intune e marcar duas vezes que a Política de Proteção de Aplicativo seja direcionada à sua conta de teste.

Em segundo lugar, marcar o código-fonte para chamadas registerAccountForMAM e implementação de MAMServiceAuthenticationCallback. Se esse primeiro não for chamado no momento certo e/ou este não tiver fornecido corretamente um token válido, você não verá o prompt Portal da Empresa.

Por fim, procure nos logs (ou depurando) o código de resultado do registro ou chame getRegisteredAccountStatus explicitamente na conta. Códigos como NOT_LICENSED podem indicar problemas de configuração com a conta de teste.

Não vi a tela Obter Acesso após fazer logon (etapa 10)

Se o Portal da Empresa não tiver sido instalado anteriormente, talvez seja necessário retomar ou reiniciar totalmente o aplicativo para ver a tela Obter Acesso e ter a política corretamente imposta. Esse é um resultado esperado com base em como aplicativos integrados ao SDK aproveitam o código dentro do aplicativo Portal da Empresa.

Se você ainda não vir a tela Obter Acesso, mesmo depois de reiniciar seu aplicativo e fazer logon novamente, o SDK poderá não estar conseguindo registrar a conta ou recuperar a política para a conta. Marcar a implementação do código-fonte do MAMServiceAuthenticationCallback.

Não vi a tela para definir ou inserir um PIN de aplicativo após fazer logon (etapa 11)

Há outros aplicativos integrados ao SDK em seu dispositivo de teste? O PIN do aplicativo é compartilhado entre todos os aplicativos gerenciados e o SDK tem um temporizador global para impedir que os usuários finais sejam solicitados para o PIN em cada lançamento ou retomada de aplicativo gerenciado.

Caso contrário, visite o centro de administração do Intune e marcar que a Política de Proteção de Aplicativo tenha o PIN do aplicativo habilitado e seja direcionado para sua conta de teste.

Como último recurso, a reinicialização do dispositivo redefinirá o temporizador PIN. Se a tela PIN não aparecer depois de reiniciar seu dispositivo, provavelmente não será configurada corretamente na política.

Eu vi a tela Obter Acesso, mas capturas de tela ainda são permitidas (etapa 12)

Enquanto a política está sendo recuperada, a política errada está sendo aplicada. Primeiro, visite o centro de administração do Intune e marcar duas vezes que a Política de Proteção de Aplicativo desabilite capturas de tela e seja direcionada à sua conta de teste. Em segundo lugar, use o console de diagnóstico (descrito acima) para marcar a política que foi puxada para baixo para seu aplicativo. Se ambas as políticas confirmarem que as capturas de tela devem ser bloqueadas, marcar sua configuração de plug-in de build do Gradle para garantir que as substituições de MAM estejam sendo feitas.

Meu aplicativo parecia falhar ou fechar depois de fazer logon (etapa 13)

Quando você cancelar o registro de uma conta que foi registrada anteriormente e teve a política imposta, os dados associados a essa conta serão apagados pelo SDK. O término do processo de aplicativo é esperado.

Capturas de tela ainda estão bloqueadas mesmo depois de eu ter feito logon (etapa 14)

Marcar o código-fonte para chamadas para unregisterAccountForMAM(). Se a política ainda for imposta após o registro em log, é provável que a conta não tenha sido registrada corretamente e não registrada.

Solução de problemas de teste de proteção de dados

Seguindo as etapas de Testes de Proteção de Dados acima, você pode encontrar os seguintes comportamentos inesperados:

Meu aplicativo não está recebendo nem aplicando políticas

Primeiro, confirme se a Política de Proteção de Aplicativo é direcionada a um grupo que contém sua conta de teste. Consulte Como validar a configuração da política de proteção do aplicativo no Microsoft Intune para obter detalhes.

Em segundo lugar, marcar as Informações de Diagnóstico do cliente para confirmar que o SDK recebeu a política configurada. Se não tiver, inspecione a implementação do MAMServiceAuthenticationCallback aplicativo e chame para registerAccountForMAM. Também marcar logs ou depuração para verificar o MAMEnrollmentManager.Result.

Meu aplicativo pode compartilhar dados em um aplicativo não gerenciado

Confirme se "Enviar dados da organização para outros aplicativos" é definido como "Aplicativos gerenciados por políticas". Verifique o Microsoft Intune centro de administração para confirmar se a política está configurada e direcionada corretamente. Verifique as informações de diagnóstico do cliente para confirmar se o SDK recebeu a política configurada.

Em seguida, se a política estiver configurada e recuperada corretamente, marcar se alguma política estiver sendo imposta: meu aplicativo não está recebendo ou aplicando nenhuma política.

Meu aplicativo não pode compartilhar dados com outro aplicativo gerenciado

Confirme as configurações da Política de Proteção de Aplicativo direcionadas ao aplicativo e ao outro aplicativo gerenciado. É recomendável ter o mesmo destino de política para ambos os aplicativos. A política direcionada ao aplicativo deve ter "Enviar dados da organização para outros aplicativos" definido como "Aplicativos gerenciados por políticas". Verifique a política direcionada ao outro aplicativo; se ele tiver "Receber dados de outros aplicativos" definido como "Nenhum", esse comportamento será esperado.

Meu aplicativo pode receber dados de um aplicativo não gerenciado

Confirme se "Receber dados de outros aplicativos" é definido como "Aplicativos gerenciados por políticas". Verifique o Microsoft Intune centro de administração para confirmar se a política está configurada e direcionada corretamente. Verifique as informações de diagnóstico do cliente para confirmar se o SDK recebeu a política configurada.

Em seguida, se a política estiver configurada e recuperada corretamente, marcar se alguma política estiver sendo imposta: meu aplicativo não está recebendo ou aplicando nenhuma política.

Meu aplicativo não pode receber dados de outro aplicativo gerenciado

Confirme as configurações da Política de Proteção de Aplicativo direcionadas ao aplicativo e ao outro aplicativo gerenciado. É recomendável ter o mesmo destino de política para ambos os aplicativos. A política direcionada ao aplicativo deve ter "Receber dados de outros aplicativos" definido como "Aplicativos gerenciados por políticas". Verifique a política direcionada ao outro aplicativo; se ele tiver "Enviar dados da organização para outros aplicativos" definido como "Nenhum", esse comportamento será esperado.

Próximas etapas

Depois de concluir todos os Critérios de Saída acima, seu aplicativo agora é integrado com êxito como identidade única e pode impor todas as políticas básicas de proteção de aplicativo. As seções subsequentes, Estágio 5: Várias Identidades, Estágio 6: Configuração de Aplicativos e Estágio 7: Os Recursos de Participação do Aplicativo podem ou não ser necessários, dependendo do suporte desejado da política de proteção de aplicativo do aplicativo. Se você não tiver certeza se alguma dessas seções se aplica ao seu aplicativo, revisite As Principais Decisões para integração do SDK.