Nutzerkonten implementieren

Für Android Enterprise-Registrierungen gibt es zwei primäre Arten von Nutzeridentitäten: Managed Google Play-Konten und verwaltete Google-Konten. Managed Google Play-Konten sind geräteorientiert und nicht an die Google-Identität eines bestimmten Nutzers gebunden. Verwaltete Google-Konten sind hingegen mit der geschäftlichen Google-Identität eines Nutzers verknüpft, was die Nutzerfreundlichkeit verbessert, da die Nutzer auf ihren Geräten angemeldet bleiben.

Managed Google Play-Konten waren früher der Standard. Google empfiehlt jedoch jetzt, für alle neuen Entwicklungen den verbesserten Registrierungsvorgang zu verwenden, bei dem standardmäßig verwaltete Google-Konten erstellt werden.

Eine Anleitung für die ältere Implementierung finden Sie am Ende dieses Dokuments. Alle neuen Entwicklungen sollten jedoch dem hier beschriebenen neuen Registrierungsvorgang folgen.

Übersicht

Der verbesserte Geräte-Registrierungsvorgang optimiert die Geräteeinrichtung durch die Verwendung mehrerer neuer Komponenten und ändert die Implementierung von benutzerdefinierten Device Policy Controllern (DPCs). Dieser neue Ansatz erfordert, dass benutzerdefinierte DPC-Lösungen in das Android Management API (AMAPI) SDK und Android Device Policy integriert werden, um Funktionen zur Gerätevorbereitung und Nutzerregistrierung auszuführen.

Das AMAPI SDK bietet die erforderlichen APIs für die Interaktion mit Android Device Policy auf dem Gerät selbst. Auf der Serverseite verwenden Enterprise Mobility Management (EMM)-Lösungen die Play EMM API, um die Registrierungstokens zu generieren, die zum Starten des Geräte-Registrierungsvorgangs erforderlich sind.

Die Android Device Policy App spielt jetzt eine zentrale Rolle bei der Verarbeitung von Vorgängen auf dem Gerät. Das AMAPI SDK wird verwendet, um die Installation und die erforderlichen Updates auf dem Gerät zu verwalten. Android Device Policy übernimmt auch den Nutzerauthentifizierungsvorgang, verarbeitet die Nutzerauthentifizierung direkt und stellt dem EMM die Identität des Nutzers zur Verfügung. Wenn Google den Nutzer aus irgendeinem Grund nicht authentifizieren kann, wird als Fallback ein neues Managed Google Play-Konto erstellt und dem Gerät hinzugefügt.

Ein wichtiger Bestandteil dieses neuen Registrierungsvorgangs ist die Verwaltung des Gerätezugriffs auf Google-Dienste. Standardmäßig befinden sich Geräte in einem eingeschränkten Zustand. Der EMM spielt eine entscheidende Rolle bei der Aktivierung des Zugriffs, sobald das Gerät konform ist.

API-Integration

Prüfen Sie vor dem Start, ob Sie die neueste Version des Play EMM API-Clients und des AMAPI SDK verwenden.

Implementierungsleitfaden für die Registrierung

In diesem Leitfaden werden die erforderlichen Schritte zur Implementierung der Registrierung beschrieben. Dazu gehören die Vorbereitung der Umgebung, der Umgang mit verschiedenen Registrierungsmethoden und die Verwaltung des Gerätelebenszyklus.

Umgebung vorbereiten

Bevor Sie mit der Kontoeinrichtung beginnen, müssen Sie die Geräteumgebung vorbereiten. Dazu gehört, den Play Store auf die neueste Version zu aktualisieren und Android Device Policy (com.google.android.apps.work.clouddpc) im Hintergrund auf dem Gerät zu installieren. Die Installation von Android Device Policy ist unerlässlich, da sie wichtige Komponenten des Kontoeinrichtungsvorgangs enthält. EMMs müssen die Umgebung nicht manuell vorbereiten. Stattdessen sollten sie die EnvironmentClient verwenden, wie unter und beschrieben, und sich an die bereitgestellten Codebeispiele halten.

Beispielcode

Bevor die AccountSetup API verwendet werden kann, um das Arbeitskonto auf dem Gerät hinzuzufügen, muss der DPC zuerst prüfen, ob die Geräteumgebung bereit ist.

  • Verwenden Sie EnvironmentClientFactory , um ein EnvironmentClient zu instanziieren, und rufen Sie prepareEnvironment oder prepareEnvironmentAsyncauf.

    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]

Dieser Vorgang kann mehrere Sekunden oder Minuten dauern, da Anwendungen möglicherweise installiert oder aktualisiert werden, um eine ordnungsgemäße Arbeitsumgebung zu gewährleisten. Google empfiehlt, diesen Vorgang so früh wie möglich im Hintergrund zu starten und eine entsprechende Benutzeroberfläche anzuzeigen, während der Nutzer wartet. Nach Abschluss des Vorgangs ist das Gerät bereit, damit der DPC die AccountSetup API verwenden kann.

Registrierungsvorgang

EMMs müssen die Verwendung von users.generateAuthenticationToken() und users.insert() für alle Geräte einstellen. Stattdessen müssen EMMs die API auf dem Gerät aufrufen, um die Endnutzerauthentifizierung durchzuführen. Die neue API gibt die userId und email an den DPC zurück. Wenn Google den Nutzer nicht authentifizieren kann, wird ein Managed Google Play-Konto erstellt und dem Gerät hinzugefügt. In diesem Fall gibt Google die userId dieses Kontos zurück.

Google führt jetzt die Verwendung von Registrierungstokens ein, die an die Authentifizierungs-API übergeben werden müssen. EMMs legen fest, wann und wie das Token erstellt wird. Es kann Teil einer vorhandenen Registrierungsnutzlast sein (z. B. ein QR-Code oder eine Zero-Touch-Konfiguration).

Google empfiehlt jedoch, das Token bei Bedarf zu erstellen und die vorhandene API für Managed Google Play-Konten durch die neue API zu ersetzen, um die Änderung zu minimieren.

Typische DPC-Integration mit früheren APIs
Abbildung 1. Typische DPC-Integration mit früheren APIs
Beispiel für die DPC-Integration mit neuen APIs für gerätelose Geräte
Abbildung 2. Beispiel für die DPC-Integration mit neuen APIs für Geräte ohne Nutzerkonto
Beispiel für die DPC-Integration mit neuen APIs für Nutzergeräte
Abbildung 3. Beispiel für die DPC-Integration mit neuen APIs für Nutzergeräte

Der verbesserte benutzerdefinierte DPC-Registrierungsvorgang umfasst die folgenden Schritte:

Wichtiger anfänglicher Gerätestatus:Wenn Sie ein Gerät mit einem benutzerdefinierten DPC registrieren, befindet sich das dem Gerät hinzugefügte Google-Konto im Status deaktiviert. Das bedeutet, dass der Zugriff auf Google-Dienste, einschließlich Google Play, zunächst eingeschränkt ist.

Dieser Standardstatus „deaktiviert“ und die anschließende Anforderung, dass der EMM das Gerät als konform kennzeichnen muss (z.B. durch Aufrufen von Devices.SetState), gelten speziell unter den folgenden Bedingungen:

  1. Die Organisation hat die Inhaberschaft ihrer Domain bei Google bestätigt.
  2. Der IT-Administrator hat die Android-Mobilgeräteverwaltung durch Dritte für die spezifische Organisationseinheit (OE) des Nutzers in der Admin-Konsole explizit aktiviert.
  1. Registrierungstoken erstellen:Der EMM erstellt ein Registrierungstoken mit der Play EMM API.
  2. Umgebung vorbereiten: Der benutzerdefinierte DPC verwendet den Vorgang Umgebung vorbereiten , um zu prüfen, ob das Gerät für die Registrierung bereit ist.
  3. Registrierung starten: Der benutzerdefinierte DPC ruft die startAccountSetup API im AMAPI SDK auf und übergibt das Registrierungstoken. Hinweis: Der DPC muss entweder Geräteinhaber oder Profilinhaber sein, bevor er diese API aufruft.
  4. Google-Authentifizierungsaktivität starten:Falls erforderlich, ruft der benutzerdefinierte DPC die launchAuthenticationActivity API im AMAPI SDK auf und übergibt den AccountSetupAttempt. Dadurch wird eine Google-Authentifizierungsaktivität gestartet, die den Nutzer nach erfolgreicher Authentifizierung zum benutzerdefinierten DPC zurückführt. Der Nutzer kann diesen Vorgang auch überspringen. In diesem Fall wird dem Gerät ein Managed Google Play-Konto hinzugefügt. Diese Option kann mit googleAuthenticationOptions konfiguriert werden.
  5. Registrierung abschließen:Das AMAPI SDK benachrichtigt den benutzerdefinierten DPC über das Ergebnis der Registrierung.

  6. Google-Dienste aktivieren: Sobald der benutzerdefinierte DPC das Gerät vollständig bereitgestellt und bestätigt hat, dass es allen Unternehmensrichtlinien entspricht, muss der EMM-Server Devices.setState() aufrufen und den Parameter accountState auf "enabled" setzen.

    • Warum ist das wichtig? Mit diesem API-Aufruf wird das Gerät als konform gekennzeichnet.
    • Folgen, wenn der Aufruf nicht erfolgt:Ohne diesen Devices.setState(setStateRequest)-Aufruf bleibt das Konto im Status „deaktiviert“. Der Nutzer kann nicht auf Google Play zugreifen (um Apps zu installieren oder zu aktualisieren) und auch nicht auf andere Google-Dienste, für die eine Kontoauthentifizierung erforderlich ist.

Gerätestatus und Dienstzugriff verwalten

Nach der ersten Registrierung ist der EMM dafür verantwortlich, den Zugriff des Geräts auf Google-Dienste basierend auf dem Compliance-Status aufrechtzuerhalten.

Dienstunterbrechungen verarbeiten: BAD_DEVICE_MANAGEMENT

Wenn der Zugriff eines Geräts auf Google-Dienste blockiert ist, senden die Google Play-Dienste (GMSCore) einen Intent mit der Aktion com.google.android.gms.auth.BAD_DEVICE_MANAGEMENT. Dafür kann es verschiedene Gründe geben:

  • Der EMM hat nach der ersten Geräteregistrierung nie Devices.setState("enabled") aufgerufen.
  • Das Gerät entspricht nicht mehr den EMM-Richtlinien und der EMM hat es noch nicht wieder aktiviert.
  • Der EMM hat den Gerätestatus explizit auf „deaktiviert“ gesetzt, indem er Devices.setState() aufgerufen und accountState auf „deaktiviert“ gesetzt hat. Das kann aus Sicherheitsgründen, aufgrund administrativer Maßnahmen oder aus anderen Gründen geschehen.

Dieser Intent enthält einen Statuscode wie "ThirdPartyDeviceManagementRequired".

Benutzerdefinierte DPCs MÜSSEN einen BroadcastReceiver implementieren, um auf diesen BAD_DEVICE_MANAGEMENT Intent zu warten.

Nach Erhalt dieser Broadcast-Nachricht sollte der DPC Folgendes tun:

  1. Compliance neu bewerten:Prüfen Sie, ob das Gerät derzeit alle vom EMM festgelegten Richtlinien erfüllt.
  2. Maßnahmen ergreifen:
    • Konform:Der DPC sollte den EMM-Server benachrichtigen. Der EMM-Server sollte dann Devices.setState() aufrufen und accountState für die spezifische Nutzer-ID und Geräte-ID auf "enabled" setzen, um den Dienstzugriff wiederherzustellen.
    • Nicht konform:Sobald die Probleme behoben sind und das Gerät konform ist, sollte der EMM Devices.setState() aufrufen.

Dieser Mechanismus sorgt dafür, dass Situationen erkannt und behoben werden können, in denen ein Gerät den Zugriff auf Google-Dienste verliert.

Überlegungen zur Unternehmensübernahme

Es kann zu Änderungen am Kontotyp der Organisation kommen (z.B. von ManagedGoogleDomainType.TYPE_TEAM zu ManagedGoogleDomainType.TYPE_DOMAIN). Obwohl dieser Vorgang in der Regel die EMM-Bindung nicht unterbricht, kann er manchmal den Zugriff auf Google-Dienste auf Geräten stören.

EMMs sollten wissen, dass wenn Nutzer nach einem bekannten Übernahmeereignis Probleme mit dem Dienstzugriff melden, auch wenn das Gerät den EMM-Richtlinien entspricht, ein Aufruf von Devices.setState() erforderlich sein kann, um den Gerätestatus unter der neuen Kundenstruktur mit den Back-Ends von Google zu synchronisieren. Proaktive Aufrufe für alle Geräte nach der Übernahme sind in der Regel nicht erforderlich, aber sie sind ein wichtiges Tool zur Behebung von Zugriffsproblemen.

Kontoeinrichtung – Beispielcode

  1. Um einen Kontoeinrichtungsversuch zu starten, kann die aufrufende App AccountSetupClient verwenden und entweder die startAccountSetup() oder startAccountSetupFuture() Methode aufrufen. Ein Beispiel für die Implementierung finden Sie im folgenden Codebeispiel:

    // 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. Implementieren Sie die AccountSetupListener -Schnittstelle und geben Sie eine Implementierung für die Verarbeitung der empfangenen Statusaktualisierungen an.

  3. Erweitern Sie NotificationReceiverService und geben Sie die AccountSetupListener Instanz an, die in Schritt 2 erstellt wurde, indem Sie getAccountSetupListener() überschreiben.

    // 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. Fügen Sie die erweiterte NotificationReceiverService -Klasse zu AndroidManifest.xml hinzu und prüfen Sie, ob sie exportiert wird.

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

    Wenn Ihre App auf SDK 30 oder höher ausgerichtet ist, ist in AndroidManifest.xml ein queries-Element erforderlich, um anzugeben, dass sie mit ADP interagiert.

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

Testanleitung

In diesem Abschnitt finden Sie eine Reihe von Richtlinien und Best Practices zum Testen Ihrer Implementierung.

PrepareEnvironment testen

  1. Aktuellen Status des Geräts abrufen:Der EMM führt

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

    aus, um die Version von Android Device Policy auf dem Gerät abzurufen. Wenn Android Device Policy nicht installiert ist, wird eine leere Ausgabe erwartet.

  2. PrepareEnvironment integrieren:Der benutzerdefinierte DPC ruft die prepareEnvironment API im AMAPI SDK auf und übergibt die korrekte Anfrage.

  3. Auf das Ergebnis von PrepareEnvironment warten:Der benutzerdefinierte DPC wartet, bis prepareEnvironment abgeschlossen ist.

  4. Erfolg von PrepareEnvironment bestätigen:Nach Abschluss führt der EMM erneut

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

    aus. Die Android Device Policy-Version sollte jetzt höher sein als in Schritt 1.

Google-Kontoauthentifizierung testen

  1. Testunternehmen erstellen: Der EMM erstellt ein Google-Testunternehmen für eine Testdomain, das mit einem EMM-Test verknüpft ist, mit enterprises.generateSignupUrl.
  2. Google-Authentifizierung aktivieren: Der EMM aktiviert die Google-Authentifizierung für das Testunternehmen. Folgen Sie dazu dieser Anleitung in der Admin-Konsole.
  3. Registrierungstoken erstellen:Der EMM erstellt mit der Play EMM API ein Registrierungstoken vom Typ userDevice.
  4. Registrierung starten: Der benutzerdefinierte DPC ruft die startAccountSetup API im AMAPI SDK auf und übergibt das Registrierungstoken.
  5. Aktivität erforderlich:Das AMAPI SDK benachrichtigt den benutzerdefinierten DPC, dass eine Aktivität gestartet werden muss, um den Nutzer zu authentifizieren.
  6. Nutzer authentifizieren: Der benutzerdefinierte DPC ruft launchAuthenticationActivity auf, um die Aktivität zu starten. Der Nutzer authentifiziert sich mit einem verwalteten Google-Konto (Teil des in Schritt 1 erstellten Unternehmens).
  7. Registrierung abschließen:Das AMAPI SDK benachrichtigt den benutzerdefinierten DPC über das Ergebnis der Registrierung.

Überspringen der Google-Authentifizierung testen

Wir verwenden die zuvor beschriebene Einrichtung.

In Schritt 7 drückt der Nutzer dieses Mal auf Überspringen , anstatt sich mit seinem Google-Konto zu authentifizieren. Die Registrierung wird erfolgreich abgeschlossen, mit einem Dienst konto auf dem Gerät (d.h. der AuthenticationType ist „Anonym“).

Geräte ohne Nutzerkonto testen

Der verbesserte benutzerdefinierte DPC-Registrierungsvorgang umfasst die folgenden Schritte, wenn die Google-Authentifizierung deaktiviert ist:

  1. Testunternehmen erstellen:Das kann dasselbe Unternehmen sein, das zuvor erstellt wurde.
  2. Registrierungstoken erstellen:Der EMM erstellt mit der Play EMM API ein Registrierungstoken vom Typ userlessDevice.
  3. Registrierung starten: Der benutzerdefinierte DPC ruft die startAccountSetup API im AMAPI SDK auf und übergibt das Registrierungstoken.
  4. Registrierung abschließen:Das AMAPI SDK benachrichtigt den benutzerdefinierten DPC über das Ergebnis der Registrierung.