Implementar contas de usuário

Há dois tipos principais de identidade do usuário para registros do Android Enterprise: contas gerenciadas do Google Play e contas gerenciadas do Google. As contas gerenciadas do Google Play são focadas no dispositivo, ou seja, não estão vinculadas à identidade do Google de um usuário específico. Já as Contas do Google gerenciadas estão vinculadas à identidade corporativa do Google de um usuário, o que melhora a experiência dele, mantendo o login nos dispositivos.

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

As orientações para a implementação mais antiga são fornecidas no final deste documento para contexto, mas todo o novo desenvolvimento precisa seguir o novo fluxo de inscrição detalhado aqui.

Visão geral

O fluxo de inscrição de dispositivos aprimorado simplifica a configuração usando vários componentes novos e mudando a forma como os controladores de política de dispositivo (DPCs) personalizados são implementados. Essa nova abordagem exige soluções personalizadas de DPC para integração com o SDK da API Android Management (AMAPI) e o 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 a política de dispositivo Android no próprio dispositivo. No lado do servidor, as soluções de gerenciamento de mobilidade empresarial (EMM) usam a API Play EMM para gerar os tokens de inscrição necessários para iniciar o processo de inscrição do dispositivo.

O app Android Device Policy agora tem 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. A Android Device Policy também assume o fluxo de autenticação do usuário, processando a autenticação diretamente e fornecendo a identidade do usuário ao EMM. Se o Google não conseguir autenticar o usuário por qualquer motivo, uma nova conta do Google Play gerenciado será criada e adicionada ao dispositivo como alternativa.

Integração de API

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

Guia de implementação da inscrição

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

prepare o ambiente

Antes de iniciar a configuração da conta, é necessário preparar o ambiente do dispositivo. Essa preparação envolve atualizar a Play Store para a iteração mais recente e instalar silenciosamente o Android Device Policy (com.google.android.apps.work.clouddpc) no dispositivo. A instalação do Android Device Policy é essencial porque abriga componentes críticos do processo de configuração da conta. Os EMMs não precisam fazer 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.

Código de amostra

Antes de usar a API AccountSetup para adicionar a conta de trabalho ao 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 alguns 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 inscrição

Os EMMs precisam parar de usar users.generateAuthenticationToken() e users.insert() em todos os dispositivos. Em vez disso, as 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 gerenciada do Google Play será criada e adicionada ao dispositivo. Nesse caso, o Google vai retornar o userId dessa conta.

Agora, o Google apresenta o uso de tokens de inscrição, que precisam ser transmitidos para a API de autenticação. Os EMMs determinam quando e como criar o token, que pode fazer parte de uma carga de inscrição atual (por exemplo, um QR code ou configuração sem toque).

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

Integração típica do DPC com APIs anteriores
Figura 1. Integração típica do 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 do DPC com novas APIs para dispositivos do usuário

O fluxo aprimorado de inscrição personalizada do DPC envolve as seguintes etapas:

  1. Criar token de inscrição:o EMM cria um token de inscrição usando a API EMM do Play.
  2. Preparar o ambiente:o DPC personalizado usa o fluxo "Preparar o ambiente" para verificar se o dispositivo está pronto para o registro.
  3. Iniciar inscrição:o DPC personalizado invoca a API startAccountSetup no SDK da AMAPI, transmitindo o token de inscrição. 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, a DPC personalizada invoca a API launchAuthenticationActivity no SDK 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 bem-sucedida. 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 inscrição:o SDK da AMAPI notifica o DPC personalizado sobre o resultado da inscrição.
  6. Ativar os Serviços do Google:depois que o dispositivo de um usuário com a Conta do Google gerenciada estiver em conformidade com as políticas corporativas, o EMM precisará chamar Devices.setState(). Essa ação permite o acesso aos Serviços do Google para a conta no dispositivo. Sem essa chamada, a Play Store e outros Serviços do Google não vão funcionar.

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

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

    // 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.

            }
            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 NotificationReceiverService estendida ao seu AndroidManifest.xml e verifique se ela foi exportada.

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

    Se o app segmenta o SDK 30 ou versões mais recentes, um elemento "queries" é necessário no AndroidManifest.xml para especificar que ele vai interagir com a ADP.

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

Orientação sobre testes

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

Teste PrepareEnvironment

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

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

    para conferir a versão do Android Device Policy presente no dispositivo. Se a Política de dispositivo Android não estiver instalada, uma saída vazia será esperada.

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

  3. Aguardar o resultado de "PrepareEnvironment":o DPC personalizado aguarda a conclusão de 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 mais recente do que na etapa 1.

Testar a autenticação da Conta do Google

  1. Criar uma empresa de teste:o EMM cria um domínio de teste do Google Enterprise vinculado 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 inscrição:o EMM cria um token de inscrição usando a API Play EMM com o tipo userDevice.
  4. Iniciar inscrição:o DPC personalizado invoca a API startAccountSetup no SDK da AMAPI, transmitindo o token de inscrição.
  5. Atividade de inicialização 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 faz a autenticação com uma Conta do Google gerenciada (parte da empresa criada na etapa 1).
  7. Finalizar inscrição:o SDK da AMAPI notifica o DPC personalizado sobre o resultado da inscrição.

Testar a opção de pular a autenticação do Google

Vamos usar a configuração descrita anteriormente.

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

Testar dispositivos sem usuário

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

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