Implementare gli account utente

Esistono due tipi di identità utente principali per le registrazioni Android Enterprise: account della versione gestita di Google Play e Account Google gestiti. La versione gestita di Google Play è incentrata sul dispositivo, il che significa che non è collegata 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'accesso ai propri dispositivi.

Gli account della versione gestita di Google Play erano lo standard. Tuttavia, Google ora incoraggia tutti i nuovi sviluppi a utilizzare il flusso di registrazione migliorato, che prevede la creazione di account Google gestiti per impostazione predefinita.

Sebbene alla fine di questo documento siano fornite indicazioni per l'implementazione precedente per fornire un contesto, tutto il nuovo sviluppo deve 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 l'integrazione di soluzioni DPC personalizzate con l'SDK dell'API Android Management (AMAPI) e Android Device Policy per eseguire le funzioni di preparazione del dispositivo e registrazione degli utenti.

L'SDK AMAPI fornisce le API necessarie per interagire con Android Device Policy sul dispositivo stesso. Sul lato server, le soluzioni Enterprise Mobility Management (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 e fornendo l'identità dell'utente all'EMM. Se Google non riesce ad autenticare l'utente per qualsiasi motivo, viene creato un nuovo account versione gestita di Google Play e aggiunto al dispositivo 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 vengono avviati in uno stato limitato e l'EMM svolge un ruolo fondamentale nell'abilitazione dell'accesso una volta che il dispositivo è conforme.

Integrazione API

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

Guida all'implementazione della registrazione

Questa guida fornisce i passaggi necessari per implementare la registrazione. Vengono trattati la preparazione dell'ambiente, la gestione di diversi metodi di registrazione e la 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 prevede l'aggiornamento del Play Store alla sua ultima iterazione e l'installazione silenziosa di Android Device Policy (com.google.android.apps.work.clouddpc) sul dispositivo. L'installazione di Android Device Policy è essenziale perché contiene componenti critici del processo di configurazione dell'account. I provider EMM non devono eseguire la preparazione manuale dell'ambiente. Devono invece utilizzare EnvironmentClient, come documentato in e rispettare gli esempi di codice forniti.

Codice di esempio

Prima di poter utilizzare l'API 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 chiamare 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 adeguato. Google consiglia di avviare questo processo il prima possibile in background e di mostrare un'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. Le EMM devono invece chiamare l'API on-device per eseguire l'autenticazione dell'utente finale. La nuova API restituirà userId e email al DPC. Se Google non riesce ad autenticare l'utente, verrà creato un account Google Play gestito e aggiunto al dispositivo. In questo caso, Google restituirà l'userId di quell'account.

Google ora introduce l'utilizzo di 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 la configurazione zero-touch).

Tuttavia, Google consiglia di creare il token su richiesta e sostituire l'API esistente per gli account della versione gestita di Google Play con la nuova API per ridurre al minimo la modifica.

Integrazione DPC tipica con le API precedenti
Figura 1. Integrazione tipica di DPC con le API precedenti
Esempio di integrazione di DPC con le nuove API per i dispositivi senza utente
Figura 2. Esempio di integrazione del 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 di DPC con nuove API per i dispositivi utente

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

Importante stato iniziale 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 predefinito "disattivato" e il successivo requisito per l'EMM di contrassegnare il dispositivo come conforme (ad es. chiamando Devices.SetState) sono applicabili in modo specifico alle seguenti condizioni:

  1. L'organizzazione ha verificato la proprietà del suo dominio con Google.
  2. L'amministratore IT ha attivato esplicitamente la gestione dei dispositivi mobili Android di terze parti per l'unità organizzativa specifica dell'utente (UO) nella Console di amministrazione Google.
  1. Crea token di registrazione: la soluzione EMM crea un token di registrazione utilizzando l'API Play EMM.
  2. Prepara ambiente:il DPC personalizzato utilizza il flusso Prepara ambiente per verificare che il dispositivo sia pronto per la registrazione.
  3. Avvia registrazione: il DPC personalizzato richiama l'API startAccountSetup nell'SDK AMAPI, passando il token di registrazione. Nota: il DPC deve essere proprietario del dispositivo o del profilo prima di chiamare questa API.
  4. Avvia l'attività di autenticazione Google:se necessario, il DPC personalizzato richiama l'API launchAuthenticationActivity nell'SDK AMAPI, passando AccountSetupAttempt. Inizia un'attività di autenticazione Google, che riporta l'utente al DPC personalizzato dopo l'autenticazione riuscita. L'utente può anche saltare questo processo. In questo caso, al dispositivo verrà aggiunto un account Google Play gestito. Questa opzione può essere configurata utilizzando googleAuthenticationOptions.
  5. Finalize Enrollment (Finalizza registrazione): l'SDK AMAPI comunica al DPC personalizzato il risultato della registrazione.

  6. Attiva i servizi Google:una volta che il DPC personalizzato ha eseguito completamente il provisioning 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 app) e ad altri servizi Google che richiedono l'autenticazione dell'account.

Gestione dello stato del dispositivo e dell'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à.

Gestione delle interruzioni del servizio: BAD_DEVICE_MANAGEMENT

Se l'accesso di un dispositivo ai servizi Google è 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 dei dispositivi.
  • Il dispositivo non è più conforme alle policy EMM e l'EMM non lo ha ancora riattivato.
  • Il provider EMM ha impostato esplicitamente lo stato del dispositivo su "disattivato" chiamando Devices.setState() con accountState impostato su "disattivato". Ciò 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 rilevare questo intent BAD_DEVICE_MANAGEMENT.

Una volta ricevuta questa trasmissione, il DPC deve:

  1. Rivaluta conformità:controlla se il dispositivo soddisfa attualmente tutti i criteri impostati dall'EMM.
  2. Passa all'azione:
    • Se è conforme:il DPC deve inviare una notifica al 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 quando il dispositivo è conforme, l'EMM deve chiamare il numero Devices.setState().

Questo meccanismo garantisce un modo per rilevare e risolvere 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). Anche se questa procedura in genere non interrompe il binding EMM, a volte può interrompere l'accesso ai servizi Google sui dispositivi.

I provider EMM devono essere consapevoli che, se gli utenti segnalano problemi di accesso al servizio dopo un evento di compromissione noto, anche se il dispositivo sembra conforme alle norme EMM, potrebbe essere necessario chiamare Devices.setState() per sincronizzare nuovamente lo stato del dispositivo con i backend di Google nella nuova struttura del cliente. In genere non sono necessarie chiamate proattive per tutti i dispositivi dopo l'acquisizione, ma si tratta di uno strumento fondamentale per risolvere i problemi di accesso.

Creazione dell'account - codice campione

  1. Per avviare un tentativo di configurazione dell'account, l'app di chiamata può utilizzare AccountSetupClient e chiamare il metodo startAccountSetup() o startAccountSetupFuture(). Per un'implementazione di esempio, vedi 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 NotificationReceiverService estesa a AndroidManifest.xml e verifica che venga esportata.

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

    Se la tua app ha come target l'SDK 30 o versioni successive, è necessario un elemento queries in AndroidManifest.xml 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.

Test PrepareEnvironment

  1. Get Device's Current State: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 il criterio Android Device Policy non è installato, è previsto un output vuoto.

  2. Integra PrepareEnvironment:il DPC personalizzato richiama l'API prepareEnvironment 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, EMM viene eseguito 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.

Testare l'autenticazione dell'Account Google

  1. Crea un'azienda di test:l'EMM crea un'azienda Google con un dominio di test collegata a un EMM di test, con enterprises.generateSignupUrl.
  2. Attiva l'autenticazione Google:l'EMM attiva l'autenticazione Google per l'azienda di test seguendo queste istruzioni nella Console di amministrazione Google.
  3. Crea token di registrazione:la soluzione EMM crea un token di registrazione utilizzando l'API Play EMM con il tipo userDevice.
  4. Avvia registrazione: il DPC personalizzato richiama l'API startAccountSetup nell'SDK AMAPI, passando il token di registrazione.
  5. Attività di avvio richiesta:l'SDK AMAPI comunica 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 esegue l'autenticazione con un Account Google gestito (parte dell'azienda creata nel passaggio 1).
  7. Finalize Enrollment (Finalizza registrazione): l'SDK AMAPI comunica al DPC personalizzato il risultato della registrazione.

Testa l'omissione dell'autenticazione Google

Utilizzeremo la configurazione descritta in precedenza.

Questa volta, al 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 è anonimo).

Testare i dispositivi senza utenti

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:la soluzione EMM crea un enrollmenttoken utilizzando l'API Play EMM con il tipo userlessDevice.
  3. Avvia registrazione: il DPC personalizzato richiama l'API startAccountSetup nell'SDK AMAPI, passando il token di registrazione.
  4. Finalize Enrollment (Finalizza registrazione): l'SDK AMAPI comunica al DPC personalizzato il risultato della registrazione.