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 selbst verwalten muss, wenn sie auf Daten aus dem Internet zugreift. Aufgrund des kleinen Displays und der eingeschränkten Eingabemöglichkeiten der Smartwatch sind die Authentifizierungsoptionen, die eine Wear OS-App verwenden kann, jedoch begrenzt.

In diesem Leitfaden finden Sie eine Anleitung für die empfohlene Authentifizierungsmethode für Wear OS-Apps: Credential Manager.

Weitere Informationen zum Gestalten einer guten Anmeldeoberfläche finden Sie im UX-Leitfaden zur Anmeldung.

Vorläufige Überlegungen

Beachten Sie vor Beginn der Implementierung die folgenden Punkte.

Gastmodus

Für alle Funktionen ist keine Authentifizierung erforderlich. Bieten Sie dem Nutzer stattdessen so viele Funktionen wie möglich an, ohne dass er sich anmelden muss.

Nutzer können Ihre Wear-App entdecken und installieren, ohne die mobile App verwendet zu haben. Sie haben dann möglicherweise kein Konto und wissen nicht, welche Funktionen die App bietet. Die Funktionen des Gastmodus müssen die Funktionen Ihrer App genau widerspiegeln.

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 Funktion zur Erkennung des Handgelenks deaktiviert und das Gerät dann vom Handgelenk abnimmt, bleibt das Gerät länger entsperrt als sonst.

Wenn Ihre App ein höheres Sicherheitsniveau erfordert, z. B. beim Anzeigen potenziell vertraulicher oder privater Daten, prüfen Sie zuerst, ob die Handgelenkserkennung aktiviert ist:

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

Wenn der Rückgabewert dieser Methode false ist, fordern Sie den Nutzer auf, sich in Ihrer App in einem Konto anzumelden, bevor Sie nutzerspezifische Inhalte anzeigen.

Credential Manager

Credential Manager ist die empfohlene API für die Authentifizierung unter Wear OS. Sie bietet Nutzern eine sicherere Umgebung, um sich in einer eigenständigen Umgebung in Wear OS-Apps anzumelden, ohne dass ein verbundenes gekoppeltes Smartphone erforderlich ist und ohne dass sie sich ihr Passwort merken müssen.

In diesem Dokument werden die Informationen beschrieben, die Entwickler benötigen, um eine Credential Manager-Lösung mit den darin enthaltenen Standardauthentifizierungsverfahren zu implementieren. Diese sind:

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

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

Passkeys unter Wear OS

Entwickler werden dringend aufgefordert, Passkeys in ihren Credential Manager-Implementierungen für Wear OS 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 und kein Passwort. Das bedeutet, dass es für Hacker viel weniger Wert ist, in Server einzudringen, und dass im Falle eines Sicherheitsverstoßes viel weniger aufzuräumen ist.
• Passkeys bieten Schutz vor Phishing. Passkeys funktionieren nur bei registrierten Websites und Apps. Nutzer können nicht dazu verleitet werden, sich auf einer betrügerischen Website zu authentifizieren, da die Bestätigung vom Browser oder Betriebssystem übernommen wird.
• Passkeys machen das Senden von SMS überflüssig und machen die Authentifizierung kostengünstiger.

Passkeys implementieren

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

Einrichten

1. Legen Sie in der build.gradle-Datei des Anwendungsmoduls das Ziel-API-Level auf 35 fest:

   android {
       defaultConfig {
           targetSdkVersion(35)
       }
   }
   

2. Fügen Sie die folgenden Zeilen der Datei „build.gradle“ für Ihre App oder Ihr Modul hinzu. Verwenden Sie dabei die neueste stabile Version aus der androidx.credentials-Versionsreferenz.

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

Integrierte Authentifizierungsmethoden

Da Credential Manager eine einheitliche API ist, sind die Implementierungsschritte für Wear OS dieselben wie für jeden anderen Gerätetyp.

Mobile Anleitungen für die ersten Schritte und die Implementierung von Passkeys und Passwörtern.

Die Schritte zum Hinzufügen der Unterstützung für „Über Google anmelden“ zu Credential Manager sind auf die mobile Entwicklung ausgerichtet, aber die Schritte sind auf Wear OS dieselben. Besondere Überlegungen für diesen Fall finden Sie im Abschnitt Umstellung von der alten Funktion „Mit Google anmelden“.

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

Sekundäre Authentifizierungsmethoden

Es gibt zwei weitere akzeptable Authentifizierungsmethoden für Wear OS-Apps: OAuth 2.0 (beide Varianten) und die gemeinsame Nutzung der Mobile Auth Token Data Layer. Diese Methoden haben zwar keine Integrationspunkte in der Credential Manager API, können aber als Fallbacks in den UX-Ablauf von Credential Manager aufgenommen werden, falls Nutzer den Credential Manager-Bildschirm schließen.

Um die Nutzeraktion des Schließens des Credential Manager-Bildschirms zu verarbeiten, fangen Sie ein NoCredentialException im Rahmen Ihrer GetCredential-Logik ab und navigieren Sie zur benutzerdefinierten Authentifizierungs-UI.

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

Ihre benutzerdefinierte Authentifizierungsoberfläche kann dann eine der anderen akzeptablen Authentifizierungsmethoden bereitstellen, die im Leitfaden zur Anmelde-UX beschrieben sind.

Tokenfreigabe für die Datenschicht

Die Companion-App für Smartphones 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 ist in der Regel keine Aktion des Nutzers erforderlich. Vermeiden Sie jedoch die Authentifizierung, ohne den Nutzer darüber zu informieren, dass er angemeldet wird. Sie können den Nutzer über einen schließbaren Bildschirm darüber informieren, dass sein Konto vom 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.

Übergeben Sie Tokens über die Datenschicht der mobilen App, 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)

So hören Sie auf Ereignisse für Datenänderungen in der Wear OS App:

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 auf Wear OS senden und synchronisieren.

OAuth 2.0 verwenden

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

• Autorisierungscode-Gewährung mit Proof Key for Code Exchange (PKCE) gemäß RFC 7636
• Device Authorization Grant (DAG) gemäß Definition in RFC 8628

Hinweis :Damit Ihre App nicht geschlossen wird, wenn das Wear OS-Gerät in den Inaktivmodus wechselt, aktivieren Sie „Always-on“ mit AmbientModeSupport.attach in der Aktivität, die die Authentifizierung durchführt. Weitere Informationen zu Best Practices für den Inaktivmodus finden Sie unter Sicherstellen der Sichtbarkeit der App auf Wear.

Proof Key for Code Exchange (PKCE)

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

Der folgende Code zeigt ein Beispiel für das Erstellen einer Autorisierungsanfrage:

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

Nachdem Sie die Autorisierungsanfrage erstellt haben, senden Sie 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-UI in einem Webbrowser auf dem Smartphone des Nutzers präsentiert. 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 URL weiter, die in der Anfrage angegeben ist. 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 liegt in Form eines Abfragestrings vor und sieht 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, die den Nutzer zur Companion-App weiterleitet. Die Companion-App prüft die Antwort-URL und leitet die Antwort über die onAuthorizationResponse API an Ihre Wear OS-App weiter.

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

Hinweis :Sobald die OAuthRequest erstellt wurde, können Sie die Weiterleitungs-URL unter redirectUrl aufrufen.

Geräteautorisierung

Wenn Sie den Geräteautorisierungsfluss verwenden, öffnet der Nutzer die Bestätigungs-URI auf einem anderen Gerät. Der Autorisierungsserver fordert den Nutzer dann auf, die Anfrage zu genehmigen oder abzulehnen.

Um diesen Vorgang zu vereinfachen, können Sie einen RemoteActivityHelper verwenden, um eine Webseite auf dem gekoppelten Mobilgerät des Nutzers zu ö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 Absicht in Ihrer App abzufangen, anstatt sich darauf zu verlassen, dass der Browser das Token autorisiert.

Umstellung von der klassischen Anmeldung über Google

Credential Manager bietet einen speziellen Integrationspunkt für die Schaltfläche „Über Google anmelden“. Bisher konnte diese Schaltfläche an beliebiger Stelle in der Authentifizierungsoberfläche einer App hinzugefügt werden. Mit der Aufnahme in Credential Manager ist die alte Option jetzt jedoch veraltet.

Hinweis :Die Credential Manager-Version von „Mit Google anmelden“ ist vorübergehend auf Wear OS-Geräten mit Wear OS 3 (API-Level 30) nicht verfügbar. Wenn eine App den Credential Manager auf einem Gerät aufruft, das ihn nicht unterstützt, wird im GetCredential-Ablauf ein NoCredentialException-Fehler ausgegeben. Das bedeutet in der Regel, dass auf dem Gerät eines Nutzers keine Anmeldedaten für die aufrufende App verfügbar sind.

Um dieses Problem zu beheben, empfehlen wir, die Legacy-Version der Schaltfläche als Teil des Fallback-Authentifizierungs-UX-Ablaufs hinzuzufügen und eine boolesche Logik hinzuzufügen, um diese Schaltfläche zu deaktivieren, wenn sie auf einem Gerät mit Wear OS 4 (API-Level 33) oder höher ausgeführt wird. So können Nutzer unabhängig von den Funktionen ihres Geräts auf die gewohnte Schaltfläche „Mit Google anmelden“ zugreifen und es wird nur eine gültige Authentifizierungsoption angezeigt.

// 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+")
  }
)