Le app per Wear OS possono essere eseguite in modo autonomo, senza un'app complementare. Ciò significa che un'app per Wear OS deve gestire autonomamente l'autenticazione quando accede ai dati da internet. Tuttavia, le dimensioni ridotte dello schermo e le funzionalità di inserimento ridotte dello smartwatch limitano le opzioni di autenticazione che un'app Wear OS può utilizzare.
Questa guida fornisce indicazioni per il metodo di autenticazione consigliato per le app Wear OS, Gestore delle credenziali.
Per scoprire di più su come progettare un'esperienza di accesso ottimale, consulta la guida all'esperienza utente di accesso.
Considerazioni preliminari
Prima di iniziare l'implementazione, tieni presente i seguenti punti.
Modalità Ospite
Non richiedere l'autenticazione per tutte le funzionalità. Fornisci invece all'utente il maggior numero possibile di funzionalità senza che debba accedere.
Gli utenti potrebbero scoprire e installare la tua app per Wear senza aver utilizzato l'app mobile, quindi potrebbero non avere un account e non sapere quali funzionalità offre. Assicurati che la funzionalità della modalità ospite mostri con precisione le funzionalità della tua app.
Alcuni dispositivi potrebbero rimanere sbloccati più a lungo
Sui dispositivi supportati con Wear OS 5 o versioni successive, il sistema rileva se l'utente indossa il dispositivo sul polso. Se l'utente disattiva il rilevamento del polso e poi toglie il dispositivo dal polso, il sistema mantiene il dispositivo sbloccato per un periodo di tempo più lungo rispetto a quanto farebbe altrimenti.
Se la tua app richiede un livello di sicurezza più elevato, ad esempio quando mostra dati potenzialmente sensibili o privati, controlla innanzitutto se il rilevamento del polso è attivo:
val wristDetectionEnabled =
isWristDetectionAutoLockingEnabled(applicationContext)
Se il valore restituito di questo metodo è false, chiedi all'utente di accedere a un account nella tua app prima di mostrare contenuti specifici per l'utente.
Gestore delle credenziali
Credential Manager è l'API consigliata per l'autenticazione su Wear OS. Offre un ambiente più sicuro per consentire agli utenti di accedere alle applicazioni Wear OS in un ambiente autonomo, senza bisogno di uno smartphone accoppiato connesso e senza dover ricordare la password.
Questo documento illustra le informazioni necessarie per implementare una soluzione di gestione delle credenziali con i meccanismi di autenticazione standard che ospita, ovvero:
- Passkey
- Password
- Identità federate (ad esempio Accedi con Google)
Questa guida fornisce inoltre indicazioni su come eseguire la migrazione degli altri metodi di autenticazione accettabili per Wear OS (condivisione di token di livello dati e OAuth) come backup per Gestore delle credenziali e indicazioni speciali per gestire la transizione dal pulsante Accedi con Google autonomo ora non più supportato alla versione incorporata di Gestore delle credenziali.
Passkey su Wear OS
Gli sviluppatori sono vivamente incoraggiati a implementare le passkey nelle implementazioni di Gestore delle credenziali per Wear OS. Le passkey sono il nuovo standard di settore per l'autenticazione degli utenti finali e offrono diversi vantaggi significativi per gli utenti.
Le passkey sono più semplici
- Gli utenti possono selezionare un account con cui accedere. Non è necessario digitare un nome utente.
- Gli utenti possono autenticarsi utilizzando il blocco schermo del dispositivo.
- Dopo aver creato e registrato una passkey, l'utente può passare senza problemi a un nuovo dispositivo e utilizzarlo immediatamente senza dover eseguire nuovamente la registrazione.
Le passkey sono più sicure
- Gli sviluppatori salvano sul server solo una chiave pubblica anziché una password, il che significa che è molto meno vantaggioso per un malintenzionato hackerare i server e molto meno da ripulire in caso di violazione.
- Le passkey offrono una protezione a prova di phishing. Le passkey funzionano solo su app e siti web registrati. Un utente non può essere indotto con l'inganno ad autenticarsi su un sito ingannevole perché la verifica viene gestita dal browser o dal sistema operativo.
- Le passkey riducono la necessità di inviare SMS, rendendo l'autenticazione più economica.
Implementare le passkey
Include la configurazione e le indicazioni per tutti i tipi di implementazione.
Configura
Imposta il livello API target su 35 nel file build.gradle del modulo dell'applicazione:
android { defaultConfig { targetSdkVersion(35) } }Aggiungi le seguenti righe al file build.gradle della tua app o del tuo modulo, utilizzando la versione stabile più recente del riferimento alle release
androidx.credentials.androidx.credentials:credentials:1.5.0 androidx.credentials:credentials-play-services-auth:1.5.0
Metodi di autenticazione integrati
Poiché Credential Manager è un'API unificata, i passaggi di implementazione per Wear OS sono gli stessi di qualsiasi altro tipo di dispositivo.
Utilizza le istruzioni per i dispositivi mobili per iniziare e implementare il supporto di passkey e password.
I passaggi per aggiungere il supporto di Accedi con Google a Gestore delle credenziali sono rivolti allo sviluppo mobile, ma sono gli stessi su Wear OS. Consulta la sezione Transizione dall'accesso con Google precedente per considerazioni speciali per questo caso.
Tieni presente che, poiché non è possibile creare credenziali su Wear OS, non è necessario implementare i metodi di creazione delle credenziali indicati nelle istruzioni per il mobile.
Metodi di autenticazione di riserva
Esistono altri due metodi di autenticazione accettabili per le app Wear OS: OAuth 2.0 (entrambe le varianti) e la condivisione del livello dati del token di autenticazione mobile. Sebbene questi metodi non abbiano punti di integrazione nell'API Gestore delle credenziali, possono essere inclusi nel flusso UX di Gestore delle credenziali come alternative nel caso in cui gli utenti chiudano la schermata di Gestore delle credenziali.
Per gestire l'azione dell'utente di chiudere la schermata Gestore delle credenziali, acquisisci un messaggio NoCredentialException all'interno della logica GetCredential e vai alla tua interfaccia utente di autenticazione personalizzata.
yourCoroutineScope.launch {
try {
val response = credentialManager.getCredential(activity, request)
signInWithCredential(response.credential)
} catch (e: GetCredentialCancellationException) {
navigateToFallbackAuthMethods()
}
}
L'interfaccia utente di autenticazione personalizzata può quindi fornire uno degli altri metodi di autenticazione accettabili descritti nella guida all'esperienza utente di accesso.
Condivisione dei token del livello dati
L'app complementare dello smartphone può trasferire in sicurezza i dati di autenticazione all'app Wear OS utilizzando l'API Wearable Data Layer. Trasferisci le credenziali come messaggi o come elementi di dati.
Questo tipo di autenticazione in genere non richiede alcuna azione da parte dell'utente. Tuttavia, evita di eseguire l'autenticazione senza informare l'utente che è in corso l'accesso. Puoi informare l'utente utilizzando una schermata ignorabile che gli mostra che il suo account è in fase di trasferimento dal dispositivo mobile.
Importante: la tua app Wear OS deve offrire almeno un altro metodo di autenticazione, perché questa opzione funziona solo sugli smartwatch accoppiati ad Android quando è installata l'app mobile corrispondente. Fornisci un metodo di autenticazione alternativo per gli utenti che non dispongono dell'app mobile corrispondente o il cui dispositivo Wear OS è accoppiato a un dispositivo iOS.
Passa i token utilizzando il livello dati dall'app mobile, come mostrato nell'esempio seguente:
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)
Monitora gli eventi di modifica dei dati nell'app Wear OS, come mostrato nell'esempio seguente:
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.
}
}
}
}
Per ulteriori informazioni sull'utilizzo del livello dati per i dispositivi indossabili, consulta Inviare e sincronizzare i dati su Wear OS.
Utilizzare OAuth 2.0
Wear OS supporta due flussi basati su OAuth 2.0, descritti nelle sezioni seguenti:
- Concessione del codice di autorizzazione con Proof Key for Code Exchange (PKCE), come definito nel RFC 7636
- Device Authorization Grant (DAG), come definito nel documento RFC 8628
Proof Key for Code Exchange (PKCE)
Per utilizzare efficacemente PKCE, utilizza RemoteAuthClient.
Quindi, per eseguire una richiesta di autenticazione dalla tua app Wear OS a un provider OAuth,
crea un oggetto OAuthRequest. Questo oggetto è costituito da un URL all'endpoint OAuth per ottenere un token e da un oggetto CodeChallenge.
Il seguente codice mostra un esempio di creazione di una richiesta di autenticazione:
val request = OAuthRequest.Builder(this.applicationContext)
.setAuthProviderUrl(Uri.parse("https://...."))
.setClientId(clientId)
.setCodeChallenge(codeChallenge)
.build()
Dopo aver creato la richiesta di autenticazione, inviala all'app complementare utilizzando il metodo sendAuthorizationRequest():
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.
}
}
)
Questa richiesta attiva una chiamata all'app complementare, che presenta un'interfaccia utente di autorizzazione in un browser web sul cellulare dell'utente. Il fornitore OAuth 2.0 autentica l'utente e ottiene il suo consenso per le autorizzazioni richieste. La risposta viene inviata all'URL di reindirizzamento generato automaticamente.
Dopo un'autorizzazione riuscita o non riuscita, il server OAuth 2.0 reindirizza all'URL specificato nella richiesta. Se l'utente approva la richiesta di accesso, la risposta contiene un codice di autorizzazione. Se l'utente non approva la richiesta, la risposta contiene un messaggio di errore.
La risposta è sotto forma di stringa di query e ha il seguente aspetto:
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
Viene caricata una pagina che indirizza l'utente all'app complementare. L'app complementare verifica l'URL di risposta e la inoltra alla tua app Wear OS utilizzando l'API onAuthorizationResponse.
L'app dello smartwatch può quindi scambiare il codice di autorizzazione con un token di accesso.
Concesione dell'autorizzazione del dispositivo
Quando si utilizza la concessione dell'autorizzazione del dispositivo, l'utente apre l'URI di verifica su un altro dispositivo. Il server di autorizzazione chiede all'utente di approvare o rifiutare la richiesta.
Per semplificare questa procedura, utilizza un RemoteActivityHelper per aprire una pagina web sul dispositivo mobile accoppiato dell'utente, come mostrato nell'esempio seguente:
// 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.
Se hai un'app per iOS, utilizza i link universali per intercettare questo intento nella tua app anziché fare affidamento sul browser per autorizzare il token.
Transizione dall'accesso con Google precedente
Gestore delle credenziali ha un punto di integrazione dedicato per un pulsante Accedi con Google. In precedenza, questo pulsante poteva essere aggiunto ovunque nell'esperienza utente di autenticazione di un'app, ma con la sua inclusione in Gestore delle credenziali, la vecchia opzione è ora deprecata.
// 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+")
}
)