Authentifizierung auf Wearables: Anmeldedaten-Manager

Wear OS-Apps können eigenständig ohne Companion-App ausgeführt werden. Das bedeutet, dass eine Wear OS-App die Authentifizierung beim Zugriff auf Daten aus dem Internet selbst verwalten muss. Aufgrund der geringen Bildschirmgröße und der eingeschränkten Eingabemöglichkeiten der Smartwatch sind die Authentifizierungsoptionen, die eine Wear OS-App verwenden kann, jedoch begrenzt.

In diesem Leitfaden wird die empfohlene Authentifizierungsmethode für Wear OS-Apps beschrieben: der Anmeldedaten-Manager.

Weitere Informationen zum Entwerfen einer nutzerfreundlichen Anmeldung finden Sie im UX-Leitfaden für die Anmeldung.

Vorab-Überlegungen

Berücksichtigen Sie die folgenden Punkte, bevor Sie mit der Implementierung beginnen.

Gastmodus

Für alle Funktionen ist keine Authentifizierung erforderlich. Bieten Sie Nutzern stattdessen so viele Funktionen wie möglich an, ohne dass sie sich anmelden müssen.

Nutzer können Ihre Wear OS-App finden und installieren, ohne die mobile App verwendet zu haben. Daher haben sie möglicherweise kein Konto und wissen nicht, welche Funktionen die App bietet. Achten Sie darauf, dass die Funktionen des Gastmodus die Funktionen Ihrer App korrekt präsentieren.

Einige Geräte bleiben möglicherweise länger entsperrt

Auf unterstützten Geräten mit Wear OS 5 oder höher erkennt das System, ob der Nutzer das Gerät am Handgelenk trägt. Wenn der Nutzer die Erkennung des Handgelenks deaktiviert und das Gerät dann vom Handgelenk nimmt, hält das System das Gerät länger entsperrt als es sonst der Fall wäre.

Wenn für Ihre App ein höheres Sicherheitsniveau erforderlich ist, z. B. beim Anzeigen potenziell vertraulicher oder privater Daten, prüfen Sie zuerst, ob die Erkennung des Handgelenks aktiviert ist:

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

Wenn der Rückgabewert dieser Methode false ist, bitte den Nutzer, sich in einem Konto in Ihrer App anzumelden, bevor du ihm nutzerspezifische Inhalte zeigst.

Credential Manager

Die Credential Manager API ist die empfohlene API für die Authentifizierung unter Wear OS. So können sich Nutzer in einer sicheren Umgebung in Wear OS-Apps in einer eigenständigen Umgebung anmelden, ohne ein verbundenes gekoppeltes Smartphone benötigen und sich ihr Passwort merken zu müssen.

In diesem Dokument werden die Informationen beschrieben, die Entwickler benötigen, um eine Lösung für den Anmeldedaten-Manager mit den standardmäßigen Authentifizierungsmechanismen zu implementieren:

  • Passkeys
  • Passwörter
  • Föderierte Identitäten (z. B. „Über Google anmelden“)

Außerdem wird beschrieben, wie Sie die anderen zulässigen Wear OS-Authentifizierungsmethoden (Data Layer Token Sharing und OAuth) als Back-ups für den Anmeldedaten-Manager migrieren. Außerdem finden Sie hier eine spezielle Anleitung für die Umstellung von der jetzt eingestellten eigenständigen Schaltfläche „Über Google anmelden“ auf die eingebettete Version des Anmeldedaten-Managers.

Passkeys unter Wear OS

Entwicklern wird dringend empfohlen, Passkeys in ihren Wear OS-Implementierungen für den Anmeldedaten-Manager zu implementieren. Passkeys sind der neue Branchenstandard für die Endnutzerauthentifizierung und bieten Nutzern mehrere wichtige Vorteile.

Passkeys sind einfacher

  • Nutzer können ein Konto auswählen, mit dem sie sich anmelden möchten. Sie müssen keinen Nutzernamen eingeben.
  • Nutzer können sich mit der Displaysperre des Geräts authentifizieren.
  • Nachdem ein Passkey erstellt und registriert wurde, kann der Nutzer nahtlos zu einem neuen Gerät wechseln und es sofort verwenden, ohne sich noch einmal registrieren zu müssen.

Passkeys sind sicherer

  • Entwickler speichern nur einen öffentlichen Schlüssel auf dem Server, anstatt ein Passwort zu speichern. Das bedeutet, dass es für einen Angreifer weitaus weniger interessant ist, sich in Server zu hacken, und dass im Falle eines Sicherheitsverstoßes weitaus weniger Aufräumarbeiten anfallen.
  • Passkeys bieten einen Phishing-resistenten Schutz. Passkeys funktionieren nur auf registrierten Websites und in registrierten Apps. Nutzer können nicht dazu verleitet werden, sich auf einer betrügerischen Website zu authentifizieren, da die Überprüfung vom Browser oder Betriebssystem durchgeführt wird.
  • Passkeys reduzieren das Senden von SMS und machen die Authentifizierung kostengünstiger.

Passkeys implementieren

Enthält Einrichtung und Anleitung für alle Implementierungstypen.

Einrichten

  1. Legen Sie in der build.gradle-Datei Ihres Anwendungsmoduls die Ziel-API-Ebene auf 35 fest:

    android {
    defaultConfig {
        targetSdkVersion(35)
    }
}

  2. Fügen Sie der Datei „build.gradle“ Ihrer App oder Ihres Moduls die folgenden Zeilen hinzu. Verwenden Sie dabei die neueste stabile Version aus der Referenz androidx.credentials-Releases.

    androidx.credentials:credentials:1.5.0
androidx.credentials:credentials-play-services-auth:1.5.0

Integrierte Authentifizierungsmethoden

Da der Anmeldedaten-Manager eine einheitliche API ist, sind die Implementierungsschritte für Wear OS mit denen für andere Gerätetypen identisch.

Folgen Sie der Anleitung für Mobilgeräte, um loszulegen und die Unterstützung für Passkeys und Passwörter zu implementieren.

Die Schritte zum Hinzufügen der Unterstützung für „Über Google anmelden“ zu Credential Manager sind auf die mobile Entwicklung ausgerichtet, aber sie sind für Wear OS identisch. Im Abschnitt Übergang von der bisherigen Funktion „Über Google anmelden“ finden Sie spezielle Hinweise für diesen Fall.

Da auf Wear OS keine Anmeldedaten erstellt werden können, müssen Sie die in der Anleitung für Mobilgeräte beschriebenen Methoden zum Erstellen von Anmeldedaten nicht implementieren.

Authentifizierungsmethoden für die Sicherheit

Es gibt zwei weitere zulässige Authentifizierungsmethoden für Wear OS-Apps: OAuth 2.0 (entweder Variante) und die Freigabe der Datenebene für mobile Authentifizierungstokens. Diese Methoden haben zwar keine Integrationspunkte in der Anmeldedaten-Manager API, können aber als Fallbacks in den UX-Flow des Anmeldedaten-Managers aufgenommen werden, falls Nutzer den Anmeldedaten-Manager-Bildschirm schließen.

Wenn der Nutzer den Bildschirm des Anmeldedaten-Managers schließt, fangen Sie im Rahmen Ihrer GetCredential-Logik eine NoCredentialException ab und rufen Sie Ihre benutzerdefinierte Authentifizierungs-UI auf.

yourCoroutineScope.launch {
    try {
      val response = credentialManager.getCredential(activity, request)
      signInWithCredential(response.credential)
    } catch (e: GetCredentialCancellationException) {
      navigateToFallbackAuthMethods()
    }
}

Ihre benutzerdefinierte Authentifizierungs-UI kann dann eine der anderen zulässigen Authentifizierungsmethoden bereitstellen, die im UX-Leitfaden für die Anmeldung beschrieben sind.

Freigabe von Datenebenen-Tokens

Die Smartphone-Kompanion-App kann Authentifizierungsdaten mithilfe der Wearable Data Layer API sicher an die Wear OS-App übertragen. Anmeldedaten als Nachrichten oder als Datenelemente übertragen.

Bei dieser Art der Authentifizierung müssen Nutzer in der Regel nichts weiter tun. Führen Sie die Authentifizierung jedoch nicht durch, ohne den Nutzer darüber zu informieren, dass er angemeldet wird. Sie können den Nutzer über einen ausgeblendeten Bildschirm darüber informieren, dass sein Konto von einem Mobilgerät übertragen wird.

Wichtig:Ihre Wear OS-App muss mindestens eine weitere Authentifizierungsmethode anbieten, da diese Option nur auf mit Android gekoppelten Smartwatches funktioniert, wenn die entsprechende mobile App installiert ist. Bieten Sie eine alternative Authentifizierungsmethode für Nutzer an, die die entsprechende mobile App nicht haben oder deren Wear OS-Gerät mit einem iOS-Gerät gekoppelt ist.

Über die Datenebene der mobilen App übergebene Tokens, wie im folgenden Beispiel gezeigt:

val token = "..." // Auth token to transmit to the Wear OS device.
val dataClient: DataClient = Wearable.getDataClient(context)
val putDataReq: PutDataRequest = PutDataMapRequest.create("/auth").run {
    dataMap.putString("token", token)
    asPutDataRequest()
}
val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)

Sie können in der Wear OS App nach Datenänderungsereignissen suchen, wie im folgenden Beispiel gezeigt:

val dataClient: DataClient = Wearable.getDataClient(context)
dataClient.addListener{ dataEvents ->
    dataEvents.forEach { event ->
        if (event.type == DataEvent.TYPE_CHANGED) {
            val dataItemPath = event.dataItem.uri.path ?: ""
            if (dataItemPath.startsWith("/auth")) {
                val token = DataMapItem.fromDataItem(event.dataItem).dataMap.getString("token")
                // Display an interstitial screen to notify the user that
                // they're being signed in.
                // Then, store the token and use it in network requests.
            }
        }
    }
}

Weitere Informationen zur Verwendung der Wearable Data Layer finden Sie unter Daten in Wear OS senden und synchronisieren.

OAuth 2.0 verwenden

Wear OS unterstützt zwei OAuth 2.0-basierte Abläufe, die in den folgenden Abschnitten beschrieben werden:

  • Autorisierungscode-Genehmigung mit Proof Key for Code Exchange (PKCE) gemäß RFC 7636
  • Device Authorization Grant (DAG), wie in RFC 8628 definiert
Proof Key for Code Exchange (PKCE)

Verwenden Sie RemoteAuthClient, um PKCE effektiv zu nutzen. Wenn Sie dann eine Authentifizierungsanfrage von Ihrer Wear OS-App an einen OAuth-Anbieter senden möchten, erstellen Sie ein OAuthRequest-Objekt. Dieses Objekt besteht aus einer URL zu deinem OAuth-Endpunkt zum Abrufen eines Tokens und einem CodeChallenge-Objekt.

Im folgenden Code wird ein Beispiel für die Erstellung einer Authentifizierungsanfrage gezeigt:

val request = OAuthRequest.Builder(this.applicationContext)
    .setAuthProviderUrl(Uri.parse("https://...."))
    .setClientId(clientId)
    .setCodeChallenge(codeChallenge)
    .build()

Nachdem du die Authentifizierungsanfrage erstellt hast, sende sie mit der Methode sendAuthorizationRequest() an die Companion App:

val client = RemoteAuthClient.create(this)
client.sendAuthorizationRequest(request,
    { command -> command?.run() },
    object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in
            // network requests.
        }

        override fun onAuthorizationError(errorCode: Int) {
            // Handle any errors.
        }
    }
)

Diese Anfrage löst einen Aufruf an die Companion-App aus, die dann eine Autorisierungs-Benutzeroberfläche in einem Webbrowser auf dem Smartphone des Nutzers anzeigt. Der OAuth 2.0-Anbieter authentifiziert den Nutzer und holt die Einwilligung des Nutzers für die angeforderten Berechtigungen ein. Die Antwort wird an die automatisch generierte Weiterleitungs-URL gesendet.

Nach einer erfolgreichen oder fehlgeschlagenen Autorisierung leitet der OAuth 2.0-Server zur in der Anfrage angegebenen URL weiter. Wenn der Nutzer die Zugriffsanfrage genehmigt, enthält die Antwort einen Autorisierungscode. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung.

Die Antwort hat die Form eines Suchstrings und sieht in etwa so aus:

  https://wear.googleapis.com/3p_auth/com.your.package.name?code=xyz
  https://wear.googleapis-cn.com/3p_auth/com.your.package.name?code=xyz

Dadurch wird eine Seite geladen, über die der Nutzer zur Companion App weitergeleitet wird. Die Companion App überprüft die Antwort-URL und leitet die Antwort mithilfe der onAuthorizationResponse API an Ihre Wear OS-App weiter.

Die Smartwatch-App kann den Autorisierungscode dann gegen ein Zugriffstoken eintauschen.

Geräteautorisierung gewähren

Bei der Geräteautorisierung öffnet der Nutzer den Bestätigungs-URI auf einem anderen Gerät. Der Autorisierungsserver bittet ihn dann, die Anfrage zu genehmigen oder abzulehnen.

Um diesen Vorgang zu vereinfachen, können Sie mit RemoteActivityHelper eine Webseite auf dem gekoppelten Mobilgerät des Nutzers öffnen, wie im folgenden Beispiel gezeigt:

// Request access from the authorization server and receive Device Authorization
// Response.
val verificationUri = "..." // Extracted from the Device Authorization Response.
RemoteActivityHelper.startRemoteActivity(
    this,
    Intent(Intent.ACTION_VIEW)
        .addCategory(Intent.CATEGORY_BROWSABLE)
        .setData(Uri.parse(verificationUri)),
    null
)
// Poll the authorization server to find out if the user completed the user
// authorization step on their mobile device.

Wenn Sie eine iOS-App haben, verwenden Sie universelle Links, um diese Intents in Ihrer App abzufangen, anstatt sich auf den Browser zur Autorisierung des Tokens zu verlassen.

Von der alten Version von „Über Google anmelden“ auf die neue Version umstellen

Credential Manager hat einen speziellen Integrationspunkt für die Schaltfläche „Über Google anmelden“. Bisher konnte diese Schaltfläche überall in der Authentifizierungs-UX einer App hinzugefügt werden. Da sie jetzt aber in den Anmeldedaten-Manager aufgenommen wurde, wird die alte Option eingestellt.

// Define a basic SDK check.
fun isCredentialManagerAvailable(): Boolean {
 return android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.VANILLA_ICE_CREAM
}

// Elsewhere in the code, use it to selectively disable the legacy option.
Button(
  onClick = {
    if (isCredentialManagerAvailable()) {
      Log.w(TAG, "Devices on API level 35 or higher should use
                  Credential Manager for Sign in with Google")
    } else {
      navigateToSignInWithGoogle()
    }},
  enabled = !isCredentialManagerAvailable(),
  label = { Text(text = stringResource(R.string.sign_in_with_google)) },
  secondaryLabel = { Text(text = "Disabled on API level 35+")
  }
)