Nutzer mit „Über Google anmelden“ authentifizieren

Mit Über Google anmelden kannst du die Nutzerauthentifizierung schnell in deine Android-App einbinden. Nutzer können sich mit ihrem Google-Konto bei deiner App anmelden, ihre Einwilligung geben und ihre Profilinformationen sicher mit deiner App teilen. Mit der Jetpack-Bibliothek von Android ist diese Integration reibungslos und über eine einzige API auf allen Android-Geräten einheitlich.

In diesem Dokument erfahren Sie, wie Sie „Über Google anmelden“ in Android-Apps implementieren, die Benutzeroberfläche der Schaltfläche „Über Google anmelden“ einrichten und die app-optimierte Registrierung und Anmeldung mit One Tap konfigurieren. „Über Google anmelden“ unterstützt die automatische Anmeldung für eine reibungslose Gerätemigration. Dank der plattformübergreifenden Funktionsweise auf Android-, iOS- und Weboberflächen kannst du deine App auf jedem Gerät anmelden.

So richten Sie die Funktion „Über Google anmelden“ ein:

„Über Google anmelden“ als Option für die Benutzeroberfläche des unteren Sheets des Anmeldedaten-Managers konfigurieren Diese Option kann so konfiguriert werden, dass der Nutzer automatisch zur Anmeldung aufgefordert wird. Wenn Sie entweder Passkeys oder Passwörter implementiert haben, können Sie alle relevanten Anmeldedatentypen gleichzeitig anfordern, damit sich der Nutzer nicht an die Option erinnern muss, die er zuvor für die Anmeldung verwendet hat.

Untere Ansicht des Anmeldedaten-Managers
Abbildung 1: UI für die Auswahl der Anmeldedaten im Credential Manager-Menü

Fügen Sie der Benutzeroberfläche Ihrer App die Schaltfläche „Über Google anmelden“ hinzu. Die Schaltfläche „Über Google anmelden“ bietet Nutzern eine optimierte Möglichkeit, sich mit ihren bestehenden Google-Konten in 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 explizit ihr Google-Konto für die Registrierung und Anmeldung verwenden möchten. Für Entwickler bedeutet das ein einfacheres Onboarding von Nutzern und weniger Probleme bei der Registrierung.

Animation, die den Ablauf der Anmeldung über Google zeigt
Abbildung 2: Benutzeroberfläche der Schaltfläche „Über Google anmelden“ des Credential Manager

In diesem Dokument wird beschrieben, wie Sie die Schaltfläche „Über Google anmelden“ und das Dialogfeld für das untere Steuerfeld mit der Credential Manager API mithilfe der Google ID-Hilfsbibliothek integrieren.

Google API Console-Projekt einrichten

  1. Öffnen Sie Ihr Projekt in der API Console oder erstellen Sie ein Projekt, falls Sie noch keins haben.
  2. Achten Sie darauf, dass alle Informationen auf dem OAuth-Zustimmungsbildschirm vollständig und korrekt sind.
    1. Achte darauf, dass deiner App der richtige App-Name, das App-Logo und die App-Startseite zugewiesen sind. Diese Werte werden Nutzern beim Anmelden auf dem Einwilligungsbildschirm für „Über Google anmelden“ und auf dem Bildschirm Drittanbieter-Apps und ‐Dienste angezeigt.
    2. Achten Sie darauf, dass Sie die URLs der Datenschutzerklärung und der Nutzungsbedingungen Ihrer App angegeben haben.
  3. Erstellen Sie auf der Seite „Anmeldedaten“ eine Android-Client-ID für Ihre Anwendung, 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 Anwendungstyp Android aus.
  4. Erstellen Sie auf der Seite „Anmeldedaten“ eine neue Client-ID vom Typ „Webanwendung“, falls Sie das noch nicht getan haben. Die Felder „Autorisierte JavaScript-Quellen“ und „Autorisierte Weiterleitungs-URIs“ können Sie vorerst ignorieren. Anhand dieser Client-ID wird Ihr Backend-Server identifiziert, 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 in der build.gradle-Datei Ihres Moduls Abhängigkeiten mit der aktuellen 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 Sign-in-Anfrage erstellen

Beginnen Sie mit der Implementierung, indem Sie eine Google-Anmeldungsanfrage erstellen. Verwende 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, mit denen er sich bereits in Ihrer App angemeldet hat. Rufen Sie dazu die API mit dem Parameter setFilterByAuthorizedAccounts auf, der auf true festgelegt ist. Nutzer können sich für die Anmeldung für eines der verfügbaren Konten entscheiden.

Wenn keine autorisierten Google-Konten verfügbar sind, sollte der Nutzer aufgefordert werden, sich mit einem seiner verfügbaren Konten anzumelden. 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 einzigen Konto registrieren. Das ermöglicht eine nahtlose Nutzung auf verschiedenen Geräten, insbesondere bei der Gerätemigration, wenn Nutzer schnell wieder auf ihr Konto zugreifen können, ohne ihre Anmeldedaten noch einmal eingeben zu müssen. Für Ihre Nutzer wird dadurch unnötige Reibung vermieden, wenn sie bereits zuvor angemeldet waren.

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 eine Anmeldedatenanfrage, die mit der Anfrage übereinstimmt. Das kann ein Google-Konto oder ein Passwort sein. 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 in den Google-Kontoeinstellungen nicht 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()

Achten Sie bei der Implementierung der automatischen Anmeldung auf die korrekte Abmeldung, damit Nutzer immer das richtige Konto auswählen können, nachdem sie sich ausdrücklich von Ihrer App abgemeldet haben.

Nonce festlegen, um die Sicherheit zu verbessern

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

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 richten Sie einen „Über Google anmelden“-Vorgang ein:

  1. Erstellen Sie eine Instanz von GetCredentialRequest und fügen Sie dann die zuvor erstellte googleIdOption mit addCredentialOption() 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. Wenn die API erfolgreich war, extrahiere 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. Wandeln Sie das Objekt mit der Methode GoogleIdTokenCredential.createFrom in ein GoogleIdTokenCredential-Objekt um.
  5. Wenn die Umwandlung erfolgreich war, extrahiere die GoogleIdTokenCredential-ID, überprüfe sie und authentifiziere die Anmeldedaten auf deinem Server.

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

  7. Unbekannte benutzerdefinierte Anmeldedatentypen erfassen

val request: GetCredentialRequest = Builder()
  .addCredentialOption(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 the ID to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
          // You can use the members of googleIdTokenCredential directly for UX
          // purposes, but don't use them to store or control access to user
          // data. For that you first need to validate the token:
          // pass googleIdTokenCredential.getIdToken() to the backend server.
          GoogleIdTokenVerifier verifier = ... // see validation instructions
          GoogleIdToken idToken = verifier.verify(idTokenString);
          // To get a stable account identifier (e.g. for storing user data),
          // use the subject ID:
          idToken.getPayload().getSubject()
        } 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")
    }
  }
}

Ablauf der Schaltfläche „Über Google anmelden“ auslösen

Verwende GetSignInWithGoogleOption anstelle von GetGoogleIdOption, um den Vorgang für die Schaltfläche „Über Google anmelden“ auszulösen:

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

Verarbeitet das zurückgegebene GoogleIdTokenCredential 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 auf ähnliche Weise wie im Abschnitt Über Google anmelden beschrieben.

Registrierung für neue Nutzer aktivieren (empfohlen)

Mit „Über Google anmelden“ können Nutzer ganz einfach mit nur wenigen Fingertipps ein neues Konto in Ihrer App oder Ihrem Dienst erstellen.

Wenn keine gespeicherten Anmeldedaten gefunden werden (getGoogleIdOption gibt keine Google-Konten zurück), bitte den Nutzer, sich zu registrieren. Prüfen Sie zuerst, ob es bereits zuvor verwendete Konten gibt.setFilterByAuthorizedAccounts(true) Wenn keine gefunden werden, bitte den Nutzer, sich mit seinem Google-Konto anzumelden. Verwende dazu setFilterByAuthorizedAccounts(false).

Beispiel:

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

Nachdem du die Google-Registrierungsanfrage erstellt hast, starte den Authentifizierungsvorgang. Wenn Nutzer „Über Google anmelden“ nicht für die Registrierung verwenden möchten, können Sie Ihre App für das automatische Ausfüllen optimieren. Nachdem der Nutzer ein Konto erstellt hat, können Sie ihn als letzten Schritt zur Kontoerstellung für Passkeys registrieren.

Abmeldung verarbeiten

Wenn ein Nutzer sich von Ihrer App abmeldet, rufen Sie die API-Methode clearCredentialState() auf, um den aktuellen Anmeldedatenstatus des Nutzers bei allen Anmeldedatenanbietern zu löschen. Dadurch werden alle Anmeldedatenanbieter 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 die Anmeldeoptionen für zukünftige Aufrufe von „get-credential“ einzuschränken. So können beispielsweise die aktiven Anmeldedaten gegenüber anderen verfügbaren Anmeldedaten priorisiert werden. Wenn sich ein Nutzer explizit von Ihrer App abmeldet und Sie die vollständigen Anmeldeoptionen beim nächsten Mal sehen möchten, sollten Sie diese API aufrufen, damit der Anbieter alle gespeicherten Anmeldedatensitzungen löscht.