Nutzerkonten implementieren

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

Früher waren Managed Google Play-Konten der Standard. Google empfiehlt jedoch, dass alle neuen Entwicklungen den verbesserten Registrierungsablauf verwenden, bei dem standardmäßig Managed Google-Konten erstellt werden.

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

Übersicht

Der verbesserte Ablauf für die Geräteregistrierung optimiert die Geräteeinrichtung durch die Verwendung mehrerer neuer Komponenten und die Änderung der Implementierung benutzerdefinierter Device Policy Controller (DPCs). Für diesen neuen Ansatz müssen benutzerdefinierte DPC-Lösungen in das Android Management API (AMAPI) SDK und die 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 der Android-Geräterichtlinie auf dem Gerät selbst. Auf der Serverseite werden in Enterprise Mobility Management-Lösungen (EMM) die Registrierungstokens, die zum Starten der Geräteregistrierung erforderlich sind, mithilfe der Play EMM API generiert.

Die Android Device Policy App spielt jetzt eine zentrale Rolle bei der Verarbeitung von geräteseitigen Vorgängen. Mit dem AMAPI SDK werden die Installation und die erforderlichen Updates auf dem Gerät verwaltet. Android Device Policy übernimmt auch den Nutzerauthentifizierungsvorgang, indem die Nutzerauthentifizierung direkt durchgeführt und die Identität des Nutzers an das EMM weitergegeben wird. Wenn Google den Nutzer aus irgendeinem Grund nicht authentifizieren kann, wird ein neues Managed Google Play-Konto erstellt und dem Gerät als Fallback hinzugefügt.

API-Integration

Prüfen Sie vorab, ob Sie die aktuelle Version des Play EMM API-Clients und des AMAPI SDK verwenden.

Implementierungsleitfaden für die Registrierung

In diesem Leitfaden finden Sie die erforderlichen Schritte für die Implementierung der Registrierung. Darin wird beschrieben, wie Sie die Umgebung vorbereiten, verschiedene Registrierungsmethoden verwenden und den Lebenszyklus von Geräten verwalten.

Umgebung vorbereiten

Bevor Sie mit der Einrichtung des Kontos beginnen, müssen Sie die Geräteumgebung vorbereiten. Dazu gehört, den Play Store auf die neueste Version zu aktualisieren und die Android Device Policy App (com.google.android.apps.work.clouddpc) im Hintergrund auf dem Gerät zu installieren. Die Installation der Android Device Policy App ist unerlässlich, da sie wichtige Komponenten des Kontoeinrichtungsprozesses enthält. EMMs müssen die Umgebung nicht manuell vorbereiten. Stattdessen sollten sie die EnvironmentClient verwenden, wie in der Dokumentation 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 eine EnvironmentClient zu instanziieren und prepareEnvironment oder prepareEnvironmentAsync aufzurufen.

    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 einige Sekunden oder Minuten dauern, da möglicherweise Anwendungen installiert oder aktualisiert werden müssen, um eine ordnungsgemäße Arbeitsumgebung zu gewährleisten. Google empfiehlt, diesen Vorgang so früh wie möglich im Hintergrund zu starten und dem Nutzer während der Wartezeit eine entsprechende Benutzeroberfläche anzuzeigen. Wenn der Vorgang abgeschlossen ist, kann der DPC die AccountSetup API verwenden.

Registrierungsvorgang

EMMs müssen die Verwendung von users.generateAuthenticationToken() und users.insert() für alle Geräte einstellen. Stattdessen müssen EMMs die On-Device-API aufrufen, um die Endnutzerauthentifizierung durchzuführen. Die neue API gibt userId und email an den DPC zurück. Wenn Google den Nutzer nicht authentifizieren kann, wird ein verwaltetes 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. eines QR‑Codes oder einer Zero-Touch-Konfiguration.

Google empfiehlt jedoch, das Token bei Bedarf zu erstellen und die vorhandene API für verwaltete 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ätelose Geräte
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-Registrierungsablauf umfasst die folgenden Schritte:

  1. Registrierungstoken erstellen:Das EMM erstellt ein Registrierungstoken mit der Play EMM API.
  2. Umgebung vorbereiten:Der benutzerdefinierte DPC verwendet den Ablauf „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 diese API aufgerufen wird.
  4. Google-Authentifizierungsaktivität starten:Falls erforderlich, ruft der benutzerdefinierte Geräteinhaber das launchAuthenticationActivity-API im AMAPI SDK auf und übergibt das AccountSetupAttempt. Dadurch wird eine Google-Authentifizierungsaktivität gestartet, die den Nutzer nach erfolgreicher Authentifizierung zum benutzerdefinierten DPC zurückleitet. 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 Registrierungsergebnis.
  6. Google-Dienste aktivieren:Sobald das Gerät eines Nutzers mit dem verwalteten Google-Konto den Unternehmensrichtlinien entspricht, muss der EMM-Dienst Devices.setState() aufrufen. Durch diese Aktion wird der Zugriff auf Google-Dienste für das Konto auf dem Gerät ermöglicht. Ohne diesen Aufruf funktionieren der Play Store und andere Google-Dienste nicht.

Kontoeinrichtung – Beispielcode

  1. Um einen Versuch zur Kontoeinrichtung zu starten, kann die aufrufende App AccountSetupClient verwenden und entweder die Methode startAccountSetup() oder startAccountSetupFuture() 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 an, wie die empfangenen Statusaktualisierungen verarbeitet werden sollen.

  3. Erweitern Sie NotificationReceiverService und stellen Sie die in Schritt 2 erstellte AccountSetupListener-Instanz bereit, 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.

            }
            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 Klasse NotificationReceiverService zu Ihrem 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 ein „queries“-Element im AndroidManifest.xml erforderlich, um anzugeben, dass sie mit ADP interagieren wird.

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

Anleitung zum Testen

Dieser Abschnitt enthält eine Reihe von Richtlinien und Best Practices zum Testen Ihrer Implementierung.

Test PrepareEnvironment

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

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

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

  2. PrepareEnvironment einbinden:Der benutzerdefinierte DPC ruft die prepareEnvironment-API im AMAPI SDK auf und übergibt die richtige Anfrage.

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

  4. Erfolg von „PrepareEnvironment“ bestätigen:Nach Abschluss wird EMM noch einmal ausgeführt.

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

    Die Version der Android Device Policy sollte diesmal höher sein als in Schritt 1.

Google-Kontoauthentifizierung testen

  1. Testunternehmen erstellen:Der EMM erstellt ein Google-Testunternehmen mit einer Testdomain, das mit einem Test-EMM mit enterprises.generateSignupUrl verknüpft ist.
  2. Google-Authentifizierung aktivieren:Der EMM-Anbieter aktiviert die Google-Authentifizierung für das Testunternehmen gemäß dieser Anleitung in der Admin-Konsole.
  3. Registrierungstoken erstellen:Das EMM erstellt ein Registrierungstoken mit der Play EMM API vom Typ userDevice.
  4. Registrierung starten:Der benutzerdefinierte DPC ruft die startAccountSetup-API im AMAPI SDK auf und übergibt das Registrierungstoken.
  5. Startaktivitä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 Unternehmens, das in Schritt 1 erstellt wurde).
  7. Registrierung abschließen:Das AMAPI SDK benachrichtigt den benutzerdefinierten DPC über das Registrierungsergebnis.

Überspringen der Google-Authentifizierung testen

Wir verwenden die zuvor beschriebene Einrichtung.

Dieses Mal drückt der Nutzer in Schritt 7 auf Überspringen, anstatt sich mit seinem Google-Konto zu authentifizieren. Die Registrierung wird erfolgreich abgeschlossen und auf dem Gerät ist ein Dienstkonto vorhanden (d.h. AuthenticationType ist „Anonym“).

Geräte ohne Nutzer testen

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

  1. Testunternehmen erstellen:Dies kann dasselbe Unternehmen sein, das Sie zuvor erstellt haben.
  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 Registrierungsergebnis.