Implementare gli account utente

Esistono due tipi di identità utente principali per le registrazioni di Android Enterprise: account Google Play gestiti e Account Google gestiti. Gli account Google Play gestiti sono incentrati sul dispositivo, il che significa che non sono collegati all'identità Google di un utente specifico. Al contrario, gli Account Google gestiti sono collegati all'identità Google aziendale di un utente, il che migliora l'esperienza utente mantenendo l'utente connesso sui propri dispositivi.

In precedenza, gli account Google Play gestiti erano lo standard. Tuttavia, ora Google incoraggia tutti i nuovi sviluppi a utilizzare il flusso di registrazione migliorato, che per impostazione predefinita crea Account Google gestiti.

Sebbene alla fine di questo documento siano fornite indicazioni per l'implementazione precedente a scopo di contesto, tutti i nuovi sviluppi devono seguire il nuovo flusso di registrazione descritto qui.

Panoramica

Il flusso di registrazione dei dispositivi migliorato semplifica la configurazione dei dispositivi sfruttando diversi nuovi componenti e modificando la modalità di implementazione dei controller dei criteri dei dispositivi (DPC) personalizzati. Questo nuovo approccio richiede che le soluzioni DPC personalizzate si integrino con l'SDK dell'API Android Management (AMAPI) e Android Device Policy per eseguire le funzioni di preparazione del dispositivo e di registrazione dell'utente.

L'SDK AMAPI fornisce le API necessarie per interagire con Android Device Policy sul dispositivo stesso. Sul lato server, le soluzioni di gestione della mobilità aziendale (EMM) utilizzeranno l'API Play EMM per generare i token di registrazione necessari per avviare la procedura di registrazione del dispositivo.

L'applicazione Android Device Policy ora svolge un ruolo centrale nella gestione delle operazioni lato dispositivo. L'SDK AMAPI viene utilizzato per gestire l' installazione e gli aggiornamenti necessari sul dispositivo. Android Device Policy assume anche il controllo del flusso di autenticazione dell'utente, gestendo direttamente l'autenticazione dell'utente e fornendo l'identità dell'utente all'EMM. Se Google non riesce ad autenticare l'utente per qualsiasi motivo, viene creato e aggiunto al dispositivo un nuovo account Google Play gestito come fallback.

Una parte fondamentale di questo nuovo flusso di registrazione è la gestione dell'accesso del dispositivo ai servizi Google. Per impostazione predefinita, i dispositivi iniziano in uno stato limitato e l'EMM svolge un ruolo fondamentale nell'abilitare l'accesso una volta che il dispositivo è conforme.

Integrazione API

Prima di iniziare, verifica di utilizzare l'ultima versione del client dell'API Play EMM e dell'SDK AMAPI.

Guida all'implementazione della registrazione

Questa guida fornisce i passaggi necessari per implementare la registrazione. Tratta della preparazione dell'ambiente, della gestione dei diversi metodi di registrazione e della gestione del ciclo di vita del dispositivo.

Prepara l'ambiente

Prima di avviare la configurazione dell'account, è necessario preparare l'ambiente del dispositivo. Questa preparazione comporta l'aggiornamento del Play Store alla sua ultima versione e l'installazione silenziosa di Android Device Policy (com.google.android.apps.work.clouddpc) sul dispositivo. L'installazione di Android Device Policy è essenziale in quanto contiene i componenti critici della procedura di configurazione dell'account. Gli EMM non devono eseguire la preparazione manuale dell'ambiente. Devono invece utilizzare EnvironmentClient, come documentato in e rispettare gli esempi di codice forniti.

Codice campione

Prima di poter utilizzare l' AccountSetup per aggiungere l'account di lavoro sul dispositivo, il DPC deve prima verificare che l' ambiente del dispositivo sia pronto.

  • Utilizza EnvironmentClientFactory per creare un'istanza di EnvironmentClient e chiama 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]

Questa operazione potrebbe richiedere diversi secondi o minuti, poiché le applicazioni potrebbero essere installate o aggiornate per verificare un ambiente di lavoro corretto. Google consiglia di avviare questa procedura il prima possibile in background e di mostrare l'interfaccia utente appropriata mentre l'utente attende. Al termine dell'operazione, il dispositivo è pronto per l'utilizzo dell'API AccountSetup da parte del DPC.

Flusso di registrazione

Gli EMM devono interrompere l'utilizzo di users.generateAuthenticationToken() e users.insert() per tutti i dispositivi. Devono invece chiamare l'API sul dispositivo per eseguire l'autenticazione dell'utente finale. La nuova API restituirà userId ed email al DPC. Se Google non è in grado di autenticare l'utente, verrà creato e aggiunto al dispositivo un account Google Play gestito. In questo caso, Google restituirà userId di quell'account.

Google introduce ora l'utilizzo dei token di registrazione, che devono essere passati all'API di autenticazione. Gli EMM determinano quando e come creare il token, che può far parte di un payload di registrazione esistente (ad es. un codice QR o una configurazione Zero-touch).

Esenzione per i token di registrazione esistenti

Alcuni clienti utilizzano token di registrazione con date di scadenza lunghe per eseguire registrazioni ripetute. Per garantire che questi flussi di lavoro esistenti non vengano interrotti, tutti i token creati PRIMA dell'attivazione del requisito "Autenticati utilizzando Google" sono esenti dalle nuove richieste di accesso. Questi token precedenti continueranno a funzionare come prima, consentendo agli utenti di registrare i dispositivi senza eseguire la procedura di autenticazione di Google. Tuttavia, tutti i token creati DOPO l'attivazione del requisito di autenticazione di Google seguiranno le nuove regole di autenticazione. Ciò significa che i dispositivi che utilizzano questi token più recenti richiederanno agli utenti di autenticarsi in base alle impostazioni scelte dall'amministratore IT.

Google consiglia di creare il token on demand e di sostituire l'API esistente per gli account Google Play gestiti con la nuova API per ridurre al minimo la modifica.

Integrazione tipica di DPC con le API precedenti
Figura 1. Integrazione DPC tipica con le API precedenti
Esempio di integrazione di DPC con nuove API per dispositivi senza utente
Figura 2. Esempio di integrazione DPC con le nuove API per i dispositivi senza utente
Esempio di integrazione del DPC con le nuove API per i dispositivi degli utenti
Figura 3. Esempio di integrazione DPC con le nuove API per i dispositivi utente

Il flusso di registrazione DPC personalizzato migliorato prevede i seguenti passaggi:

Stato iniziale importante del dispositivo: quando registri un dispositivo con un DPC personalizzato, l'Account Google aggiunto al dispositivo inizia in uno stato disattivato. Ciò significa che l'accesso ai servizi Google, incluso Google Play, è inizialmente limitato.

Questo stato "disattivato" predefinito e il successivo requisito che l'EMM contrassegni il dispositivo come conforme (ad es. chiamando Devices.SetState) sono applicabili in modo specifico in queste condizioni:

  1. L'organizzazione ha verificato la proprietà del proprio dominio con Google.
  2. L'amministratore IT ha abilitato esplicitamente la gestione dei dispositivi mobili Android di terze parti per l'unità organizzativa (UO) specifica dell'utente nella Console di amministrazione Google.
  1. Crea token di registrazione: l'EMM crea un token di registrazione utilizzando l'API Play EMM.
  2. Prepara l'ambiente: il DPC personalizzato utilizza il flusso di preparazione dell'ambiente per verificare che il dispositivo sia pronto per la registrazione.
  3. Avvia la registrazione: il DPC personalizzato richiama l'startAccountSetup API nell'SDK AMAPI, passando il token di registrazione. Nota: prima di chiamare questa API, il DPC deve essere il proprietario del dispositivo o del profilo.
  4. Avvia l'attività di autenticazione di Google: se necessario, il DPC personalizzato richiama l' launchAuthenticationActivity API nell'SDK AMAPI, passando AccountSetupAttempt. Viene avviata un'attività di autenticazione di Google, che riporta l'utente al DPC personalizzato dopo l'autenticazione. L'utente può anche saltare questa procedura. In questo caso, al dispositivo verrà aggiunto un account Google Play gestito. Questa opzione può essere configurata utilizzando googleAuthenticationOptions.
  5. Finalizza la registrazione: l'SDK AMAPI notifica al DPC personalizzato il risultato della registrazione.
  6. Abilita i servizi Google: una volta che il DPC personalizzato ha eseguito il provisioning completo del dispositivo e ha confermato che è conforme a tutte le policy aziendali, il server EMM deve chiamare Devices.setState() con il parametro accountState impostato su "enabled".
  • Perché è essenziale: questa chiamata API contrassegna il dispositivo come conforme.
  • Conseguenza della mancata chiamata: senza questa chiamata Devices.setState(setStateRequest), l'account rimane nello stato "disattivato". L'utente non potrà accedere a Google Play (per installare o aggiornare le app) e ad altri servizi Google che richiedono l'autenticazione dell'account.

Gestire lo stato del dispositivo e l'accesso ai servizi

Dopo la registrazione iniziale, l'EMM è responsabile del mantenimento dell'accesso del dispositivo ai servizi Google in base al suo stato di conformità.

Gestire le interruzioni del servizio: BAD_DEVICE_MANAGEMENT

Se l'accesso di un dispositivo ai servizi Google viene bloccato, Google Play Services (GMSCore) trasmetterà un intent con l'azione: com.google.android.gms.auth.BAD_DEVICE_MANAGEMENT. Questo può accadere per diversi motivi:

  • L'EMM non ha mai chiamato Devices.setState("enabled") dopo la registrazione iniziale del dispositivo.
  • Il dispositivo non è più conforme alle policy EMM e l'EMM non lo ha ancora riattivato.
  • L'EMM ha impostato esplicitamente lo stato del dispositivo su "disattivato" chiamando Devices.setState() con accountState impostato su "disattivato". Questo potrebbe essere dovuto a problemi di sicurezza, azioni amministrative o altri motivi.

Questo intent include un codice di stato, ad esempio "ThirdPartyDeviceManagementRequired".

I DPC personalizzati DEVONO implementare un BroadcastReceiver per ascoltare questo intent BAD_DEVICE_MANAGEMENT.

Dopo aver ricevuto questa trasmissione, il DPC deve:

  1. Valutare nuovamente la conformità: verifica se il dispositivo soddisfa tutte le policy impostate dall'EMM.
  2. Agire:
    • Se conforme: il DPC deve notificare il server EMM. Il server EMM deve quindi chiamare Devices.setState() con accountState impostato su "enabled" per l'ID utente e l'ID dispositivo specifici per tentare di ripristinare l'accesso al servizio.
    • Se non conforme: una volta risolti i problemi e il dispositivo è conforme, l'EMM deve chiamare Devices.setState().

Questo meccanismo garantisce un modo per rilevare e ripristinare le situazioni in cui un dispositivo perde l'accesso ai servizi Google.

Considerazioni sul takeover aziendale

Possono verificarsi modifiche al tipo di account dell'organizzazione (ad es. da ManagedGoogleDomainType.TYPE_TEAM a ManagedGoogleDomainType.TYPE_DOMAIN). Sebbene questa procedura in genere non interrompa il binding EMM, a volte può interrompere l'accesso ai servizi Google sui dispositivi.

Gli EMM devono essere consapevoli che se gli utenti segnalano problemi di accesso ai servizi dopo un evento di takeover noto, anche se il dispositivo sembra conforme alle policy EMM, potrebbe essere necessaria una chiamata a Devices.setState() per risincronizzare lo stato del dispositivo con i backend di Google nella nuova struttura del cliente. In genere non sono richieste chiamate proattive per tutti i dispositivi dopo il takeover, ma è uno strumento fondamentale per risolvere i problemi di accesso.

Configurazione dell'account - codice campione

  1. Per avviare un tentativo di configurazione dell'account, l'app di chiamate può utilizzare AccountSetupClient e chiamare il metodo startAccountSetup() o startAccountSetupFuture(). Per un'implementazione di esempio, consulta il seguente esempio di codice:

    // 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 l'interfaccia AccountSetupListener e fornisci un'implementazione per la gestione degli aggiornamenti di stato ricevuti.

  3. Estendi NotificationReceiverService e fornisci l'istanza AccountSetupListener creata nel passaggio 2 eseguendo l'override di 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. Aggiungi la classe estesa NotificationReceiverService a AndroidManifest.xml e verifica che sia esportata.

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

    Se la tua app ha come target l'SDK 30 o versioni successive, in AndroidManifest.xml è necessario un elemento queries per specificare che interagirà con ADP.

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

Indicazioni per i test

Questa sezione fornisce un insieme di linee guida e best practice per testare l'implementazione.

Testa PrepareEnvironment

  1. Ottieni lo stato attuale del dispositivo: l'EMM esegue

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

    per ottenere la versione di Android Device Policy presente sul dispositivo. Se Android Device Policy non è installato, è previsto un output vuoto.

  2. Integra PrepareEnvironment: il DPC personalizzato richiama l'prepareEnvironment API nell'SDK AMAPI, passando la richiesta corretta.

  3. Attendi il risultato di PrepareEnvironment: il DPC personalizzato attende il completamento di prepareEnvironment.

  4. Conferma l'esito positivo di PrepareEnvironment: al termine, l'EMM esegue di nuovo

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

    Questa volta la versione di Android Device Policy dovrebbe essere superiore a quella del passaggio 1.

Testa l'autenticazione dell'Account Google

  1. Crea un'azienda di test: l'EMM crea un'azienda Google di dominio di test collegata a un EMM di test, con enterprises.generateSignupUrl.
  2. Abilita l'autenticazione Google: l'EMM abilita l'autenticazione Google per l'azienda di test seguendo queste istruzioni nella Console di amministrazione Google.
  3. Crea token di registrazione: l'EMM crea un token di registrazione utilizzando l'API Play EMM con il tipo userDevice.
  4. Avvia la registrazione: il DPC personalizzato richiama l'startAccountSetup API nell'SDK AMAPI, passando il token di registrazione.
  5. Avvia l'attività richiesta: l'SDK AMAPI notifica al DPC personalizzato che deve essere avviata un'attività per autenticare l'utente.
  6. Autentica l'utente: il DPC personalizzato richiama launchAuthenticationActivity per avviare l'attività. L'utente si autentica con un Account Google gestito (parte dell'azienda creata nel passaggio 1).
  7. Finalizza la registrazione: l'SDK AMAPI notifica al DPC personalizzato il risultato della registrazione.

Testa l'omissione dell'autenticazione Google

Utilizzeremo la configurazione descritta in precedenza.

Questa volta, nel passaggio 7, l'utente preme Salta anziché autenticarsi con il proprio Account Google. La registrazione viene completata correttamente, con un account di servizio sul dispositivo (ovvero AuthenticationType è Anonymous).

Testa i dispositivi senza utente

Il flusso di registrazione DPC personalizzato migliorato utilizza i seguenti passaggi quando l'autenticazione Google è disattivata:

  1. Crea un'azienda di test: può essere la stessa azienda creata in precedenza.
  2. Crea token di registrazione: l'EMM crea un token di registrazione utilizzando l'API Play EMM con il tipo userlessDevice.
  3. Avvia la registrazione: il DPC personalizzato richiama l'startAccountSetup API nell'SDK AMAPI, passando il token di registrazione.
  4. Finalizza la registrazione: l'SDK AMAPI notifica al DPC personalizzato il risultato della registrazione.