Anmeldedaten-Manager in „Über Google anmelden“ einbinden

Mit Über Google anmelden kannst du die Nutzerauthentifizierung schnell in deine Android-App integrieren. Nutzer können sich mit ihrem Google-Konto in deiner App anmelden, einwilligen und ihre Profilinformationen sicher mit deiner App teilen. Die Jetpack-Bibliothek des Android-Anmeldedatenmanagers ermöglicht eine reibungslose Integration und sorgt für eine einheitliche Nutzung auf allen Android-Geräten über eine einzige API.

In diesem Dokument wird beschrieben, wie Sie „Über Google anmelden“ in Android-Apps implementieren, die Benutzeroberfläche der Schaltfläche „Über Google anmelden“ einrichten und für Apps optimierte Registrierungen und Anmeldungen mit nur einmal tippen konfigurieren. Für eine reibungslose Gerätemigration unterstützt „Über Google anmelden“ die automatische Anmeldung. Dank der plattformübergreifenden Struktur auf Android-, iOS- und Web-Oberflächen kannst du die Anmeldung für deine App auf jedem Gerät ermöglichen.

So richten Sie „Über Google anmelden“ ein:

„Über Google anmelden“ als Option für die Benutzeroberfläche des Anmeldedaten-Managers am unteren Rand konfigurieren Diese Einstellung kann so konfiguriert werden, dass der Nutzer automatisch zur Anmeldung aufgefordert wird. Wenn Sie Passkeys oder Passwörter implementiert haben, können Sie alle relevanten Arten von Anmeldedaten gleichzeitig anfordern, sodass sich Nutzer nicht mehr an die Option erinnern müssen, die sie zuvor zur Anmeldung verwendet haben.

Anmeldedaten-Manager am unteren Rand
Abbildung 1: Die Benutzeroberfläche zur Auswahl der Anmeldedaten am unteren Rand des Anmeldedaten-Managers

Fügen Sie der Benutzeroberfläche Ihrer App die Schaltfläche „Über Google anmelden“ hinzu. Die Schaltfläche „Über Google anmelden“ bietet Nutzern eine einfache Möglichkeit, sich mit ihren vorhandenen Google-Konten bei Android-Apps zu registrieren oder anzumelden. Nutzer klicken auf die Schaltfläche „Über Google anmelden“, wenn sie die Benutzeroberfläche am unteren Rand schließen oder ihr Google-Konto explizit für die Registrierung und Anmeldung verwenden möchten. Für Entwickler bedeutet dies ein einfacheres Onboarding von Benutzern und weniger Reibungspunkte bei der Registrierung.

Animation des „Über Google anmelden“-Vorgangs
Abbildung 2: Benutzeroberfläche der Schaltfläche „Über Google anmelden“ des Anmeldedaten-Managers

In diesem Dokument wird erläutert, wie Sie die Schaltfläche „Über Google anmelden“ und das Dialogfeld am unteren Rand mithilfe der Hilfsbibliothek Google ID in die Credential Manager API einbinden.

Projekt in der Google APIs Console einrichten

  1. Öffnen Sie Ihr Projekt in der API Console oder erstellen Sie ein Projekt, falls Sie noch keines haben.
  2. Achte darauf, dass auf der Seite für den OAuth-Zustimmungsbildschirm alle Informationen vollständig und korrekt sind.
    1. Achten Sie darauf, dass Ihrer App der App-Name, das App-Logo und die App-Startseite korrekt zugewiesen sind. Diese Werte werden Nutzern bei der Registrierung auf dem „Über Google anmelden“-Zustimmungsbildschirm und auf dem Bildschirm Drittanbieter-Apps und ‐Dienste angezeigt.
    2. Sie müssen die URLs der Datenschutzerklärung und den Nutzungsbedingungen Ihrer App angegeben haben.
  3. Erstellen Sie auf der Seite „Anmeldedaten“ eine Android-Client-ID für Ihre App, falls Sie noch keine haben. Sie müssen den Paketnamen und die SHA-1-Signatur Ihrer App angeben.
    1. Rufen Sie die Seite Anmeldedaten auf.
    2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
    3. Wählen Sie als App-Typ Android aus.
  4. Erstellen Sie auf der Seite „Anmeldedaten“ eine neue Client-ID vom Typ „Webanwendung“, falls noch nicht geschehen. Die Felder „Autorisierte JavaScript-Quellen“ und „Autorisierte Weiterleitungs-URIs“ können Sie vorerst ignorieren. Diese Client-ID wird zur Identifizierung Ihres Back-End-Servers verwendet, wenn er mit den Authentifizierungsdiensten von Google kommuniziert.
    1. Rufen Sie die Seite Anmeldedaten auf.
    2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
    3. Wählen Sie den Webanwendungstyp aus.

Abhängigkeiten deklarieren

Deklarieren Sie Abhängigkeiten in der build.gradle-Datei Ihres Moduls mit der neuesten Version des Anmeldedaten-Managers:

dependencies {
  // ... other dependencies

  implementation "androidx.credentials:credentials:<latest version>"
  implementation "androidx.credentials:credentials-play-services-auth:<latest version>"
  implementation "com.google.android.libraries.identity.googleid:googleid:<latest version>"
}

Google Log-in-Anfrage instanziieren

Um mit der Implementierung zu beginnen, stellen Sie eine Google Log-in-Anfrage ein. Verwenden Sie GetGoogleIdOption, um das Google-ID-Token eines Nutzers abzurufen.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Prüfen Sie zuerst, ob der Nutzer Konten hat, die bereits zur Anmeldung bei Ihrer App verwendet wurden. Rufen Sie dazu die API auf und setzen Sie den Parameter setFilterByAuthorizedAccounts auf true. Nutzer können bei der Anmeldung zwischen verfügbaren Konten wählen.

Wenn keine autorisierten Google-Konten verfügbar sind, sollte der Nutzer aufgefordert werden, sich mit einem der verfügbaren Konten zu registrieren. Fordern Sie dazu den Nutzer auf, indem Sie die API noch einmal aufrufen und setFilterByAuthorizedAccounts auf false setzen. Weitere Informationen zur Registrierung

Automatische Anmeldung für wiederkehrende Nutzer aktivieren (empfohlen)

Entwickler sollten die automatische Anmeldung für Nutzer aktivieren, die sich mit ihrem einzelnen Konto registrieren. Dies ermöglicht eine nahtlose Nutzung auf allen Geräten, insbesondere während der Gerätemigration, bei der Nutzer schnell wieder Zugriff auf ihr Konto erhalten, ohne ihre Anmeldedaten noch einmal eingeben zu müssen. Für Nutzer, die bereits angemeldet waren, werden dadurch unnötige Abläufe beseitigt.

Verwenden Sie setAutoSelectEnabled(true), um die automatische Anmeldung zu aktivieren. Die automatische Anmeldung ist nur möglich, wenn die folgenden Kriterien erfüllt sind:

  • Es gibt nur ein Ausweisdokument, das mit der Anfrage übereinstimmt. Dabei kann es sich um ein Google-Konto oder ein Passwort handeln. Diese Anmeldedaten stimmen mit dem Standardkonto auf dem Android-Gerät überein.
  • Der Nutzer hat sich nicht explizit abgemeldet.
  • Der Nutzer hat die automatische Anmeldung nicht in den Google-Kontoeinstellungen deaktiviert.
val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Achte bei der Implementierung der automatischen Anmeldung darauf, dass die Abmeldung korrekt gehandhabt wird, damit Nutzer immer das richtige Konto auswählen können, nachdem sie sich explizit von deiner App abgemeldet haben.

Nonce für mehr Sicherheit einrichten

Fügen Sie setNonce hinzu, um in jede Anfrage eine Nonce aufzunehmen, um die Sicherheit bei der Anmeldung zu verbessern und Replay-Angriffe zu vermeiden. Weitere Informationen zum Generieren einer Nonce.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

„Über Google anmelden“-Vorgang erstellen

So richtest du einen „Über Google anmelden“-Vorgang ein:

  1. Instanziieren Sie das GetCredentialRequest und fügen Sie das zuvor erstellte googleIdOption hinzu, um die Anmeldedaten abzurufen.
  2. Übergeben Sie diese Anfrage an den Aufruf getCredential() (Kotlin) oder getCredentialAsync() (Java), um die verfügbaren Anmeldedaten des Nutzers abzurufen.
  3. Extrahieren Sie nach erfolgreicher API die CustomCredential, die das Ergebnis für GoogleIdTokenCredential-Daten enthält.
  4. Der Typ für CustomCredential sollte dem Wert von GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL entsprechen. Konvertieren Sie das Objekt mithilfe der Methode GoogleIdTokenCredential.createFrom in ein GoogleIdTokenCredential-Objekt.

  5. Wenn die Konvertierung erfolgreich ist, extrahieren Sie die GoogleIdTokenCredential-ID, validieren Sie sie und authentifizieren die Anmeldedaten auf Ihrem Server.

  6. Wenn die Konvertierung mit einer GoogleIdTokenParsingException fehlschlägt, musst du möglicherweise die Version der Über Google-Bibliothek anmelden aktualisieren.

  7. Erkennen Sie alle unbekannten benutzerdefinierten Anmeldedatentypen.

val request: GetCredentialRequest = Builder()
  .addGetCredentialOption(googleIdOption)
  .build()

coroutineScope.launch {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    handleFailure(e)
  }
}

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {

    // Passkey credential
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse on your server to
      // validate and authenticate
      responseJson = credential.authenticationResponseJson
    }

    // Password credential
    is PasswordCredential -> {
      // Send ID and password to your server to validate and authenticate.
      val username = credential.id
      val password = credential.password
    }

    // GoogleIdToken credential
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

„Über Google anmelden“-Vorgang auslösen

Wenn du den Vorgang für die Schaltfläche „Über Google anmelden“ auslösen möchtest, verwende GetSignInWithGoogleOption anstelle von GetGoogleIdOption:

val signInWithGoogleOption: GetSignInWithGoogleOption = GetSignInWithGoogleOption.Builder()
  .setServerClientId(WEB_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Verarbeite das zurückgegebene GoogleIdTokenCredential-Element wie im folgenden Codebeispiel beschrieben.

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      }
      else -> {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Nachdem Sie die Google-Anmeldeanfrage instanziiert haben, starten Sie den Authentifizierungsvorgang ähnlich wie im Abschnitt Über Google anmelden beschrieben.

Registrierung für neue Nutzer aktivieren (empfohlen)

„Über Google anmelden“ ist für Nutzer die einfachste Möglichkeit, mit nur wenigen Fingertipps ein neues Konto bei deiner App oder deinem Dienst zu erstellen.

Wenn keine gespeicherten Anmeldedaten gefunden werden (also keine Google-Konten von getGoogleIdOption zurückgegeben wurden), bitten Sie den Nutzer, sich zu registrieren. Prüfen Sie zuerst, ob setFilterByAuthorizedAccounts(true) vorhanden ist, um zu sehen, ob zuvor verwendete Konten vorhanden sind. Wenn keine gefunden werden, fordere den Nutzer auf, sich mit setFilterByAuthorizedAccounts(false) mit seinem Google-Konto zu registrieren.

Beispiel:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(SERVER_CLIENT_ID)
  .build()

Sobald Sie die Google-Registrierungsanfrage instanziiert haben, starten Sie den Authentifizierungsvorgang. Wenn Nutzer sich nicht bei Google registrieren möchten, können Sie Autofill-Dienste oder Passkeys für die Kontoerstellung verwenden.

Abmeldung

Wenn sich ein Nutzer von Ihrer Anwendung abmeldet, rufen Sie die API-Methode clearCredentialState() auf, um den aktuellen Status der Nutzeranmeldedaten von allen Anbietern zu löschen. Dadurch werden alle Anbieter von Anmeldedaten darüber informiert, dass alle gespeicherten Anmeldedatensitzungen für die jeweilige Anwendung gelöscht werden sollen.

Ein Anmeldedatenanbieter hat möglicherweise eine aktive Anmeldedatensitzung gespeichert und verwendet diese, um Anmeldeoptionen für zukünftige „get-credential“-Aufrufe zu beschränken. Beispielsweise werden den aktiven Anmeldedaten möglicherweise Vorrang vor allen anderen verfügbaren Anmeldedaten eingeräumt. Wenn sich Ihr Nutzer explizit von Ihrer Anwendung abmeldet und um beim nächsten Mal die ganzheitlichen Anmeldeoptionen zu erhalten, sollten Sie diese API aufrufen, damit der Anbieter alle gespeicherten Anmeldedatensitzung löschen kann.