Implementar contas de usuário

Há dois tipos principais de identidade de usuário para registros do Android Enterprise: contas do Google Play gerenciado e Contas do Google gerenciadas. As contas do Google Play gerenciado são centradas no dispositivo, ou seja, não estão vinculadas à identidade do Google de um usuário específico. Por outro lado, as Contas do Google gerenciadas estão vinculadas à identidade corporativa do Google de um usuário, o que melhora a experiência do usuário, mantendo-o conectado aos dispositivos.

As contas do Google Play gerenciado costumavam ser o padrão. No entanto, o Google agora incentiva todos os novos desenvolvimentos a usar o fluxo de registro aprimorado, que cria Contas do Google gerenciadas por padrão.

Embora as orientações para a implementação mais antiga sejam fornecidas no final deste documento para contexto, todos os novos desenvolvimentos precisam seguir o novo fluxo de registro detalhado aqui.

Visão geral

O fluxo de registro de dispositivos aprimorado simplifica a configuração do dispositivo, aproveitando vários novos componentes e mudando a forma como os controladores de política de dispositivo (DPCs) personalizados são implementados. Essa nova abordagem exige que as soluções personalizadas de DPC sejam integradas ao SDK da API Android Management (AMAPI) e ao Android Device Policy para realizar funções de preparação de dispositivos e inscrição de usuários.

O SDK da AMAPI fornece as APIs necessárias para interagir com o Android Device Policy no próprio dispositivo. No lado do servidor, as soluções de gerenciamento de mobilidade empresarial (EMM) usarão a API Play EMM para gerar os tokens de registro necessários para iniciar o processo de registro do dispositivo.

O aplicativo Android Device Policy agora assume um papel central no processamento de operações do lado do dispositivo. O SDK da AMAPI é usado para gerenciar a instalação e as atualizações necessárias no dispositivo. O Android Device Policy também assume o fluxo de autenticação do usuário, processando a autenticação do usuário diretamente e fornecendo a identidade do usuário ao EMM. Se o Google não puder autenticar o usuário por qualquer motivo, uma nova conta do Google Play gerenciado será criada e adicionada ao dispositivo como alternativa.

Uma parte fundamental desse novo fluxo de registro é o gerenciamento do acesso do dispositivo aos Serviços do Google. Por padrão, os dispositivos são iniciados em um estado restrito, e o EMM desempenha um papel crucial na ativação do acesso quando o dispositivo está em compliance.

Integração de API

Antes de começar, verifique se você está usando a versão mais recente do cliente da API Play EMM e do SDK da AMAPI.

Guia de implementação de registro

Este guia fornece as etapas necessárias para implementar o registro. Ele aborda a preparação do ambiente, o processamento de diferentes métodos de registro e o gerenciamento do ciclo de vida do dispositivo.

Preparar o ambiente

Antes de iniciar a configuração da conta, é necessário preparar o ambiente do dispositivo. Essa preparação envolve a atualização da Google Play Store para a versão mais recente e a instalação silenciosa do Android Device Policy (com.google.android.apps.work.clouddpc) no dispositivo. A instalação do Android Device Policy é essencial, pois ele contém componentes críticos do processo de configuração da conta. Os EMMs não precisam realizar a preparação manual do ambiente. Em vez disso, eles precisam usar o EnvironmentClient, conforme documentado em e seguir os exemplos de código fornecidos.

Exemplo de código

Antes de usar a AccountSetup para adicionar a conta de trabalho no dispositivo, o DPC precisa verificar se o ambiente do dispositivo está pronto.

  • Use EnvironmentClientFactory para instanciar um EnvironmentClient e chame prepareEnvironment ou prepareEnvironmentAsync

    val notificationReceiverServiceName = ComponentName(context,
NotificationReceiver::class.java)

// An EMM should implement android.app.admin.DeviceAdminReceiver and use that
// class to instantiate a ComponentName

val admin = ComponentName(this, com.example.dpc.DeviceAdminReceiver::class.java)

EnvironmentClientFactory.create(context)
    .prepareEnvironment(
        PrepareEnvironmentRequest.builder()
            .setRoles(
                listOf(
                    Role.builder().setRoleType(
                        Role.RoleType.DEVICE_POLICY_CONTROLLER
                    ).build()
                )
            )
    .setAdmin(admin)
            .build(),
          notificationReceiverServiceName,
        )

[Proceed with AccountSetup]

Essa operação pode levar vários segundos ou minutos, já que os aplicativos podem ser instalados ou atualizados para verificar um ambiente de trabalho adequado. O Google recomenda iniciar esse processo o mais cedo possível em segundo plano e mostrar a interface adequada enquanto o usuário espera. Quando a operação for concluída, o dispositivo estará pronto para o DPC usar a API AccountSetup.

Fluxo de registro

Os EMMs precisam interromper o uso de users.generateAuthenticationToken() e users.insert() para todos os dispositivos. Em vez disso, os EMMs precisam chamar a API no dispositivo para realizar a autenticação do usuário final. A nova API vai retornar o userId e o email para o DPC. Se o Google não conseguir autenticar o usuário, uma conta do Google Play gerenciado será criada e adicionada ao dispositivo. Nesse caso, o Google vai retornar o userId dessa conta.

O Google agora apresenta o uso de tokens de registro, que precisam ser transmitidos à API de autenticação. Os EMMs determinam quando e como criar o token, e ele pode fazer parte de um payload de registro atual (por exemplo, um QR code ou uma configuração Zero-touch).

No entanto, o Google recomenda criar o token sob demanda e substituir a API atual de contas do Google Play gerenciado pela nova API para minimizar a mudança.

Integração típica do DPC com APIs anteriores
Figura 1. Integração típica de DPC com APIs anteriores
Exemplo de integração do DPC com novas APIs para dispositivos sem usuário
Figura 2. Exemplo de integração de DPC com novas APIs para dispositivos sem usuário
Exemplo de integração de DPC com novas APIs para dispositivos do usuário
Figura 3. Exemplo de integração de DPC com novas APIs para dispositivos de usuário

O fluxo de registro de DPC personalizado aprimorado envolve as seguintes etapas:

Estado inicial importante do dispositivo:ao registrar um dispositivo com um DPC personalizado, a Conta do Google adicionada ao dispositivo começa em um estado desativado. Isso significa que o acesso aos Serviços do Google, incluindo o Google Play, é inicialmente restrito.

Esse status "desativado" padrão e o requisito subsequente para o EMM marcar o dispositivo como em compliance (por exemplo, chamando Devices.SetState) são aplicáveis especificamente nestas condições:

  1. A organização verificou a propriedade do domínio com o Google.
  2. O administrador de TI ativou explicitamente o gerenciamento de dispositivos móveis Android de terceiros para a unidade organizacional (UO) específica do usuário no Google Admin Console.
  1. Criar token de registro:o EMM cria um token de registro usando a API Play EMM.
  2. Preparar o ambiente: o DPC personalizado usa o fluxo de preparação do ambiente para verificar se o dispositivo está pronto para o registro.
  3. Iniciar o registro: o DPC personalizado invoca a startAccountSetup API no SDK da AMAPI, transmitindo o token de registro. Observação: o DPC precisa ser o proprietário do dispositivo ou do perfil antes de chamar essa API.
  4. Iniciar a atividade de autenticação do Google:se necessário, o DPC personalizado invoca a API launchAuthenticationActivity no SDK da AMAPI, transmitindo o AccountSetupAttempt. Isso inicia uma atividade de autenticação do Google, retornando o usuário ao DPC personalizado após a autenticação. O usuário também pode pular esse processo. Nesse caso, uma conta do Google Play gerenciado será adicionada ao dispositivo. Essa opção pode ser configurada usando googleAuthenticationOptions.
  5. Finalizar o registro:o SDK da AMAPI notifica o DPC personalizado do resultado do registro.

  6. Ativar os Serviços do Google: depois que o DPC personalizado provisionar totalmente o dispositivo e confirmar que ele está em compliance com todas as políticas corporativas, o servidor EMM precisa chamar Devices.setState() com o parâmetro accountState definido como "enabled".

    • Por que isso é essencial:essa chamada de API marca o dispositivo como em compliance.
    • Consequência de não chamar:sem essa chamada Devices.setState(setStateRequest), a conta permanece no estado "desativado". O usuário não poderá acessar o Google Play (para instalar ou atualizar apps) e outros Serviços do Google que exigem autenticação de conta.

Gerenciar o estado do dispositivo e o acesso ao serviço

Após o registro inicial, o EMM é responsável por manter o acesso do dispositivo aos Serviços do Google com base no status de compliance.

Como lidar com interrupções de serviço: BAD_DEVICE_MANAGEMENT

Se o acesso de um dispositivo aos Serviços do Google for bloqueado, o Google Play Services (GMSCore) vai transmitir uma intent com a ação: com.google.android.gms.auth.BAD_DEVICE_MANAGEMENT. Esse problema pode ocorrer por vários motivos:

  • O EMM nunca chamou Devices.setState("enabled") após o registro do dispositivo inicial.
  • O dispositivo não está mais em compliance com as políticas do EMM, e o EMM ainda não o reativou.
  • O EMM definiu explicitamente o estado do dispositivo como "desativado" chamando Devices.setState() com accountState definido como "desativado". Isso pode ser devido a problemas de segurança, ações administrativas ou outros motivos.

Essa intent inclui um código de status, como "ThirdPartyDeviceManagementRequired".

Os DPCs personalizados PRECISAM implementar um BroadcastReceiver para detectar essa intent BAD_DEVICE_MANAGEMENT.

Ao receber essa transmissão, o DPC precisa:

  1. Reavaliar a compliance:verifique se o dispositivo atende a todas as políticas definidas pelo EMM.
  2. Tomar medidas:
    • Se estiver em compliance:o DPC precisa notificar o servidor EMM. Em seguida, o servidor EMM precisa chamar Devices.setState() com accountState definido como "enabled" para o ID de usuário e o ID do dispositivo específicos para tentar restaurar o acesso ao serviço.
    • Se não estiver em compliance:depois que os problemas forem resolvidos e o dispositivo estiver em compliance, o EMM precisará chamar Devices.setState().

Esse mecanismo garante que haja uma maneira de detectar e se recuperar de situações em que um dispositivo perde o acesso aos Serviços do Google.

Considerações sobre a aquisição empresarial

Mudanças no tipo de conta da organização (por exemplo, de ManagedGoogleDomainType.TYPE_TEAM para ManagedGoogleDomainType.TYPE_DOMAIN) podem ocorrer. Embora esse processo normalmente não quebre a vinculação do EMM, ele pode, às vezes, interromper o acesso ao serviço do Google em dispositivos.

Os EMMs precisam estar cientes de que, se os usuários reportarem problemas de acesso ao serviço após um evento de aquisição conhecido, mesmo que o dispositivo pareça estar em compliance com as políticas do EMM, uma chamada para Devices.setState() poderá ser necessária para sincronizar novamente o estado do dispositivo com os back-ends do Google na nova estrutura do cliente. As chamadas proativas para todos os dispositivos após a aquisição geralmente não são necessárias, mas são uma ferramenta fundamental para resolver problemas de acesso.

Configuração da conta: exemplo de código

  1. Para iniciar uma tentativa de configuração de conta, o app de ligação pode usar AccountSetupClient e chamar o método startAccountSetup() ou startAccountSetupFuture(). Para um exemplo de implementação, consulte o exemplo de código a seguir:

    // Create AccountSetupClient
val client = AccountSetupClientFactory.create(
    this,
    activityResultRegistry
)
lifecycle.addObserver(client.lifecycleObserver)

// Create adminComponent
val notificationReceiver = ComponentName(this, AccountSetupNotificationReceiver::class.java)
// Helper method to get enrollment token created with Play EMM API
val enrollmentToken = getEnrollmentToken()
val request =
    StartAccountSetupRequest.builder()
        .setEnrollmentToken(enteredText)
        .setNotificationReceiverServiceComponentName(notificationReceiver)
        .setAdminComponentName(
            ComponentName(this, com.example.dpc.DeviceAdminReceiver::class.java))
        .build()
try {
    val accountSetupAttempt = client.startAccountSetup(request)
    // handle attempt
} catch (e: Exception) {
    // handle exception
}

  2. Implemente a interface AccountSetupListener e forneça uma implementação de como processar as atualizações de status recebidas.

  3. Estenda NotificationReceiverService e forneça a instância AccountSetupListener criada na etapa 2 substituindo getAccountSetupListener().

    // Handles account setup changes
class AccountSetupNotificationReceiver :
      NotificationReceiverService(),
      AccountSetupListener {

    override fun getAccountSetupListener(): AccountSetupListener = this

    override fun onAccountSetupChanged(accountSetupAttempt:
  AccountSetupAttempt) {

        when (accountSetupAttempt.state.kind) {
            StateCase.ADDED_ACCOUNT -> {
                val enterpriseAccount = state.addedAccount()
                val userId = enterpriseAccount.userId
                val deviceId = enterpriseAccount.deviceId
                // Handle account added state.

                // IMPORTANT: The device/account is now added but *DISABLED*
                // for Google services. Your EMM backend MUST be notified to
                // perform policy compliance checks and then call Devices.setState()
                // to activate Google Play and other services.

            }
            StateCase.AUTHENTICATION_ACTIVITY_LAUNCH_REQUIRED -> {
                val request = LaunchAuthenticationActivityRequest.builder()
            .setAccountSetupAttempt(accountSetupAttempt)
            .build();
                // Send the attempt to the foreground activity to call:
                accountSetupClient.launchAuthenticationActivity(request)
            }
            StateCase.ACCOUNT_SETUP_ERROR -> {
                // Handle error state.
                val failureReason = state.accountSetupError().failureReason
            }
            else -> {
                // Handle unknown account setup attempt state.
            }
        }
    }
}

  4. Adicione a classe estendida NotificationReceiverService ao seu AndroidManifest.xml e verifique se ela foi exportada.

      <application>
    <service
        android:name = ".accountsetup.AccountSetupNotificationReceiver"
        android:exported = "true" />
  </application>

    Se o app segmentar o SDK 30 ou mais recente, um elemento de consultas será necessário no AndroidManifest.xml para especificar que ele vai interagir com o ADP.

      <queries>
    <package android:name="com.google.android.apps.work.clouddpc" />
  </queries>

Orientação de teste

Esta seção fornece um conjunto de diretrizes e práticas recomendadas para testar sua implementação.

Testar PrepareEnvironment

  1. Receber o estado atual do dispositivo: o EMM executa

    adb shell dumpsys package com.google.android.apps.work.clouddpc | grep versionName

    para receber a versão do Android Device Policy presente no dispositivo. Se o Android Device Policy não estiver instalado, uma saída vazia será esperada.

  2. Integrar o PrepareEnvironment: o DPC personalizado invoca a prepareEnvironment API no SDK da AMAPI, transmitindo a solicitação correta.

  3. Aguardar o resultado do PrepareEnvironment:o DPC personalizado aguarda a conclusão do prepareEnvironment.

  4. Confirmar o sucesso do PrepareEnvironment:após a conclusão, o EMM é executado novamente

    adb shell dumpsys package com.google.android.apps.work.clouddpc | grep versionName

    Desta vez, a versão do Android Device Policy precisa ser maior do que na etapa 1.

Testar a autenticação da Conta do Google

  1. Criar uma empresa de teste: o EMM cria uma empresa do Google de domínio de teste vinculada a um EMM de teste, com enterprises.generateSignupUrl.
  2. Ativar a autenticação do Google: o EMM ativa a autenticação do Google para a empresa de teste seguindo estas instruções no Google Admin Console.
  3. Criar token de registro:o EMM cria um token de registro usando a API Play EMM com o tipo userDevice.
  4. Iniciar o registro: o DPC personalizado invoca a startAccountSetup API no SDK da AMAPI, transmitindo o token de registro.
  5. Atividade necessária:o SDK da AMAPI notifica o DPC personalizado de que uma atividade precisa ser iniciada para autenticar o usuário.
  6. Autenticar o usuário: o DPC personalizado invoca launchAuthenticationActivity para iniciar a atividade. O usuário se autentica com uma Conta do Google gerenciada (parte da empresa criada na etapa 1).
  7. Finalizar o registro:o SDK da AMAPI notifica o DPC personalizado do resultado do registro.

Testar a omissão da autenticação do Google

Vamos usar a configuração descrita anteriormente.

Desta vez, na etapa 7, o usuário pressiona Pular em vez de autenticar com a Conta do Google. O registro é concluído com sucesso, com uma conta de serviço no dispositivo (ou seja, o AuthenticationType é anônimo).

Testar dispositivos sem usuário

O fluxo de registro de DPC personalizado aprimorado usa as etapas a seguir quando a autenticação do Google está desativada:

  1. Criar uma empresa de teste:pode ser a mesma empresa criada anteriormente.
  2. Criar token de registro:o EMM cria um token de registro usando a API Play EMM com o tipo userlessDevice.
  3. Iniciar o registro: o DPC personalizado invoca a startAccountSetup API no SDK da AMAPI, transmitindo o token de registro.
  4. Finalizar o registro:o SDK da AMAPI notifica o DPC personalizado do resultado do registro.