Implementa cuentas de usuario

Existen dos tipos principales de identidad de usuario para las inscripciones de Android Enterprise: las cuentas de Google Play administrado y las Cuentas de Google administradas. Las cuentas de Google Play administrado se centran en el dispositivo, lo que significa que no están vinculadas a la identidad de Google de un usuario específico. En cambio, las Cuentas de Google administradas están vinculadas a la identidad corporativa de Google de un usuario, lo que mejora la experiencia del usuario, ya que lo mantiene conectado en sus dispositivos.

Las cuentas de Google Play administrado solían ser el estándar. Sin embargo, ahora Google recomienda que todos los desarrollos nuevos usen el flujo de inscripción mejorado, que establece de forma predeterminada la creación de Cuentas de Google administradas.

Si bien se proporcionan instrucciones para la implementación anterior al final de este documento para brindar contexto, todos los desarrollos nuevos deben seguir el nuevo flujo de inscripción que se detalla aquí.

Descripción general

El flujo de inscripción de dispositivos mejorado optimiza la configuración de los dispositivos aprovechando varios componentes nuevos y cambiando la forma en que se implementan los controladores de políticas de dispositivos (DPC) personalizados. Este nuevo enfoque requiere que las soluciones de DPC personalizadas se integren con el SDK de la API de Android Management (AMAPI) y la Política de dispositivos Android para realizar funciones de preparación de dispositivos y de inscripción de usuarios.

El SDK de AMAPI proporciona las APIs necesarias para interactuar con la Política de dispositivos Android en el dispositivo. En el servidor, las soluciones de administración de movilidad empresarial (EMM) usarán la API de Play EMM para generar los tokens de inscripción necesarios para iniciar el proceso de inscripción del dispositivo.

La aplicación de Política de dispositivos Android ahora asume un rol central en el manejo de las operaciones del dispositivo. El SDK de AMAPI se usa para administrar su instalación y las actualizaciones necesarias en el dispositivo. La Política de dispositivos Android también se hace cargo del flujo de autenticación del usuario, ya que controla la autenticación del usuario directamente y proporciona la identidad del usuario a la EMM. Si Google no puede autenticar al usuario por algún motivo, se crea una nueva cuenta de Google Play administrado y se agrega al dispositivo como alternativa.

Una parte clave de este nuevo flujo de inscripción es administrar el acceso del dispositivo a los servicios de Google. De forma predeterminada, los dispositivos comienzan en un estado restringido, y la EMM desempeña un papel fundamental para habilitar el acceso una vez que el dispositivo cumple con los requisitos.

Integración de APIs

Antes de comenzar, verifica que estés usando la versión más reciente del cliente de la API de Play EMM y el SDK de AMAPI.

Guía de implementación de la inscripción

En esta guía, se proporcionan los pasos necesarios para implementar la inscripción. Se incluye la preparación del entorno, el manejo de diferentes métodos de inscripción y la administración del ciclo de vida del dispositivo.

Prepara el entorno

Antes de iniciar la configuración de la cuenta, es necesario preparar el entorno del dispositivo. Esta preparación implica actualizar Play Store a su versión más reciente y, luego, instalar de forma silenciosa la Política de dispositivos Android (com.google.android.apps.work.clouddpc) en el dispositivo. La instalación de la Política de dispositivos Android es esencial, ya que contiene componentes fundamentales del proceso de configuración de la cuenta. Las EMM no necesitan realizar la preparación manual del entorno. En cambio, deben usar EnvironmentClient, como se documenta en , y cumplir con los ejemplos de código proporcionados.

Código de muestra

Antes de poder usar la AccountSetup para agregar la cuenta de trabajo en el dispositivo, el DPC primero debe verificar que el entorno del dispositivo esté listo.

  • Usa EnvironmentClientFactory para crear una instancia de EnvironmentClient y llamar a prepareEnvironment o 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]

Esta operación puede tardar varios segundos o minutos, ya que es posible que se instalen o actualicen aplicaciones para verificar un entorno de trabajo adecuado. Google recomienda iniciar este proceso lo antes posible en segundo plano y mostrar la IU adecuada mientras el usuario espera. Cuando se complete la operación, el dispositivo estará listo para que el DPC use la API de AccountSetup.

Flujo de inscripción

Las EMM deben dejar de usar users.generateAuthenticationToken() y users.insert() para todos los dispositivos. En cambio, deben llamar a la API en el dispositivo para realizar la autenticación del usuario final. La nueva API mostrará el userId y el email al DPC. Si Google no puede autenticar al usuario, se creará una cuenta de Google Play administrado y se agregará al dispositivo. En este caso, Google mostrará el userId de esa cuenta.

Google ahora presenta el uso de tokens de inscripción, que deben pasarse a la API de autenticación. Las EMM determinan cuándo y cómo crear el token, y este puede formar parte de una carga útil de inscripción existente (p.ej., un código QR o una configuración de inscripción automática).

Sin embargo, Google recomienda crear el token a pedido y reemplazar la API existente para las cuentas de Google Play administrado por la nueva API para minimizar el cambio.

Integración típica del DPC con las APIs anteriores
Figura 1. Integración típica del DPC con las APIs anteriores
Ejemplo de integración del DPC con las nuevas APIs para dispositivos sin usuario
Figura 2. Ejemplo de integración del DPC con las nuevas APIs para dispositivos sin usuarios
Ejemplo de integración del DPC con las nuevas APIs para dispositivos del usuario
Figura 3. Ejemplo de integración del DPC con las nuevas APIs para dispositivos de usuario

El flujo de inscripción de DPC personalizado mejorado incluye los siguientes pasos:

Estado inicial importante del dispositivo: Cuando se inscribe un dispositivo con un DPC personalizado, la Cuenta de Google que se agrega al dispositivo comienza en un estado inhabilitado. Esto significa que el acceso a los servicios de Google, incluido Google Play, está restringido inicialmente.

Este estado "inhabilitado" predeterminado y el requisito posterior de que la EMM marque el dispositivo como compatible (p.ej., llamando a Devices.SetState) se aplican específicamente en las siguientes condiciones:

  1. La organización verificó la propiedad de su dominio con Google.
  2. El administrador de TI habilitó explícitamente la administración de dispositivos móviles Android de terceros para la unidad organizativa (UO) específica del usuario en la Consola del administrador de Google.
  1. Crear token de inscripción: La EMM crea un token de inscripción con la API de Play EMM.
  2. Preparar el entorno: El DPC personalizado usa el flujo de preparación del entorno para verificar que el dispositivo esté listo para la inscripción.
  3. Iniciar inscripción: El DPC personalizado invoca la API de startAccountSetup en el SDK de AMAPI y pasa el token de inscripción. Nota: El DPC debe ser el propietario del dispositivo o del perfil antes de llamar a esta API.
  4. Iniciar actividad de autenticación de Google: Si es necesario, el DPC personalizado invoca la API de launchAuthenticationActivity en el SDK de AMAPI y pasa el AccountSetupAttempt. Esto inicia una actividad de autenticación de Google y devuelve al usuario al DPC personalizado cuando la autenticación se realiza correctamente. El usuario también puede omitir este proceso. En este caso, se agregará una cuenta de Google Play administrado al dispositivo. Esta opción se puede configurar con googleAuthenticationOptions.
  5. Finalizar inscripción: El SDK de AMAPI notifica al DPC personalizado el resultado de la inscripción.

  6. Habilitar servicios de Google: Una vez que el DPC personalizado haya aprovisionado por completo el dispositivo y confirmado que cumple con todas las políticas empresariales, el servidor de EMM debe llamar a Devices.setState() con el parámetro accountState establecido en "enabled".

    • Por qué es esencial: Esta llamada a la API marca el dispositivo como compatible.
    • Consecuencia de no llamar: Sin esta llamada a Devices.setState(setStateRequest), la cuenta permanece en el estado "inhabilitado". El usuario no podrá acceder a Google Play (para instalar o actualizar apps) ni a otros servicios de Google que requieran autenticación de la cuenta.

Administración del estado del dispositivo y el acceso al servicio

Después de la inscripción inicial, la EMM es responsable de mantener el acceso del dispositivo a los servicios de Google según su estado de cumplimiento.

Manejo de interrupciones del servicio: BAD_DEVICE_MANAGEMENT

Si se bloquea el acceso de un dispositivo a los servicios de Google, los Servicios de Google Play (GMSCore) transmitirán un intent con la acción: com.google.android.gms.auth.BAD_DEVICE_MANAGEMENT. Esto puede suceder por varios motivos:

  • La EMM nunca llamó a Devices.setState("enabled") después de la inscripción inicial del dispositivo.
  • El dispositivo ya no cumple con las políticas de EMM, y la EMM aún no lo volvió a habilitar.
  • La EMM estableció explícitamente el estado del dispositivo en "inhabilitado" llamando a Devices.setState() con accountState establecido en "disabled". Esto puede deberse a problemas de seguridad, acciones administrativas o cualquier otro motivo.

Este intent incluye un código de estado, como "ThirdPartyDeviceManagementRequired".

Los DPC personalizados DEBEN implementar un BroadcastReceiver para escuchar este intent BAD_DEVICE_MANAGEMENT.

Cuando reciba esta transmisión, el DPC debe hacer lo siguiente:

  1. Reevaluar el cumplimiento: Verifica si el dispositivo cumple actualmente con todas las políticas establecidas por la EMM.
  2. Tomar medidas:
    • Si cumple con los requisitos: El DPC debe notificar al servidor de EMM. Luego, el servidor de EMM debe llamar a Devices.setState() con accountState establecido en "enabled" para el ID de usuario y el ID de dispositivo específicos para intentar restablecer el acceso al servicio.
    • Si no cumple con los requisitos: Una vez que se resuelvan los problemas y el dispositivo cumpla con los requisitos, la EMM debe llamar a Devices.setState().

Este mecanismo garantiza que haya una forma de detectar y recuperarse de situaciones en las que un dispositivo pierde el acceso a los servicios de Google.

Consideraciones sobre la adquisición de empresas

Pueden producirse cambios en el tipo de cuenta de la organización (p.ej., de ManagedGoogleDomainType.TYPE_TEAM a ManagedGoogleDomainType.TYPE_DOMAIN). Si bien este proceso no suele interrumpir la vinculación de la EMM, a veces puede interrumpir el acceso al servicio de Google en los dispositivos.

Las EMM deben tener en cuenta que, si los usuarios informan problemas de acceso al servicio después de un evento de adquisición conocido, incluso si el dispositivo parece cumplir con las políticas de EMM, es posible que sea necesario llamar a Devices.setState() para volver a sincronizar el estado del dispositivo con los backends de Google en la nueva estructura de clientes. Por lo general, no se requieren llamadas proactivas para todos los dispositivos después de la adquisición, pero es una herramienta clave para resolver problemas de acceso.

Configuración de la cuenta: código de muestra

  1. Para iniciar un intento de configuración de la cuenta, la app que realiza la llamada puede usar AccountSetupClient y llamar al método startAccountSetup() o startAccountSetupFuture(). Para ver un ejemplo de implementación, consulta el siguiente código de muestra:

    // 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. Implementa la interfaz AccountSetupListener y proporciona una implementación para controlar las actualizaciones de estado recibidas.

  3. Extiende NotificationReceiverService y proporciona la instancia AccountSetupListener creada en el paso 2 anulando 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. Agrega la clase extendida NotificationReceiverService a tu AndroidManifest.xml y verifica que se exporte.

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

    Si tu app está orientada al SDK 30 o versiones posteriores, se necesita un elemento de consultas en AndroidManifest.xml para especificar que interactuará con ADP.

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

Guía de pruebas

En esta sección, se proporciona un conjunto de lineamientos y prácticas recomendadas para probar tu implementación.

Prueba PrepareEnvironment

  1. Obtén el estado actual del dispositivo: La EMM ejecuta

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

    para obtener la versión de la Política de dispositivos Android presente en el dispositivo. Si la Política de dispositivos Android no está instalada, se espera un resultado vacío.

  2. Integra PrepareEnvironment: El DPC personalizado invoca la prepareEnvironment API en el SDK de AMAPI y pasa la solicitud correcta.

  3. Espera el resultado de PrepareEnvironment: El DPC personalizado espera a que se complete prepareEnvironment.

  4. Confirma el éxito de PrepareEnvironment: Una vez completado, la EMM vuelve a ejecutar

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

    Esta vez, la versión de la Política de dispositivos Android debería ser más alta que en el paso 1.

Prueba la autenticación de la Cuenta de Google

  1. Crea una empresa de prueba: La EMM crea una empresa de Google de dominio de prueba vinculada a una EMM de prueba con enterprises.generateSignupUrl.
  2. Habilita la autenticación de Google: La EMM habilita la autenticación de Google para la empresa de prueba siguiendo estas instrucciones en la Consola del administrador de Google.
  3. Crea un token de inscripción: La EMM crea un token de inscripción con la API de Play EMM con el tipo userDevice.
  4. Inicia la inscripción: El DPC personalizado invoca la startAccountSetup API en el SDK de AMAPI y pasa el token de inscripción.
  5. Inicia la actividad requerida: El SDK de AMAPI notifica al DPC personalizado que se debe iniciar una actividad para autenticar al usuario.
  6. Autentica al usuario: El DPC personalizado invoca launchAuthenticationActivity para iniciar la actividad. El usuario se autentica con una Cuenta de Google administrada (parte de la empresa creada en el paso 1).
  7. Finaliza la inscripción: El SDK de AMAPI notifica al DPC personalizado el resultado de la inscripción.

Prueba la omisión de la autenticación de Google

Usaremos la configuración descrita anteriormente.

Esta vez, en el paso 7, el usuario presiona Omitir en lugar de autenticarse con su Cuenta de Google. La inscripción se completa correctamente, con una cuenta de servicio en el dispositivo (es decir, el AuthenticationType es anónimo).

Prueba dispositivos sin usuarios

El flujo de inscripción de DPC personalizado mejorado utiliza los siguientes pasos cuando la autenticación de Google está inhabilitada:

  1. Crea una empresa de prueba: Puede ser la misma empresa que se creó anteriormente.
  2. Crea un token de inscripción: La EMM crea un token de inscripción con la API de Play EMM con el tipo userlessDevice.
  3. Inicia la inscripción: El DPC personalizado invoca la startAccountSetup API en el SDK de AMAPI y pasa el token de inscripción.
  4. Finaliza la inscripción: El SDK de AMAPI notifica al DPC personalizado el resultado de la inscripción.