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 l'autenticazione autonomamente quando accede ai dati da internet. Tuttavia, le dimensioni ridotte dello schermo dello smartwatch e le funzionalità di input ridotte limitano le opzioni di autenticazione che un'app per Wear OS può utilizzare.
Questa guida fornisce indicazioni sul metodo di autenticazione consigliato per le app per Wear OS, Gestore delle credenziali.
Per scoprire di più su come progettare una buona esperienza di accesso, consulta la guida all'UX di accesso.
Considerazioni preliminari
Prima di iniziare l'implementazione, tieni presente quanto segue.
Modalità Ospite
Non richiedere l'autenticazione per tutte le funzionalità. Invece, fornisci all'utente il maggior numero possibile di funzionalità senza richiedere l'accesso.
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 al 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, verifica innanzitutto se il rilevamento del polso è attivo:
fun isWristDetectionAutoLockingEnabled(context: Context): Boolean { // Use the keyguard manager to check for the presence of a lock mechanism val keyguardManager = context.getSystemService<KeyguardManager>() val isSecured = keyguardManager?.isDeviceSecure == true // Use OEM-specific system settings to verify that on-body autolock is enabled. val isWristDetectionOn = android.provider.Settings.Global.getInt( context.contentResolver, PIXEL_WRIST_AUTOLOCK_SETTING_STATE, 0 ) == 1 return isSecured && isWristDetectionOn }
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
Gestore delle credenziali è l'API consigliata per l'autenticazione su Wear OS. Offre un ambiente più sicuro per l'accesso degli utenti alle applicazioni Wear OS in un'impostazione autonoma, senza la necessità di uno smartphone accoppiato connesso e senza dover ricordare la password.
Questo documento descrive le informazioni necessarie agli sviluppatori per implementare una soluzione Gestore delle credenziali con i meccanismi di autenticazione standard che ospita, ovvero:
- Passkey
- Password
- Identità federate (ad esempio Accedi con Google)
Questa guida fornisce anche indicazioni su come eseguire la migrazione degli altri metodi di autenticazione Wear OS accettabili (condivisione dei token del livello dati e OAuth) come backup per Gestore delle credenziali e indicazioni speciali per gestire la transizione dal pulsante Accedi con Google autonomo, ora ritirato, alla versione incorporata di Gestore delle credenziali.
Limitazioni e differenze di Wear OS
Gli sviluppatori devono tenere presente le seguenti limitazioni e differenze su Wear OS:
- Gestore delle credenziali è disponibile su Wear OS 3 e versioni successive.
- Impossibile creare credenziali su Wear OS
- Non sono supportati né il ripristino delle credenziali né i flussi di accesso ibridi.
- Solo i fornitori di credenziali con integrazioni Wear OS possono essere riutilizzati da dispositivo mobile.
Passkey su Wear OS
Consigliamo vivamente agli sviluppatori di implementare le passkey nelle loro implementazioni di Gestore delle credenziali di 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 facilmente a un nuovo dispositivo e utilizzarlo immediatamente senza dover ripetere la registrazione.
Le passkey sono più sicure
- Gli sviluppatori salvano solo una chiave pubblica sul server anziché una password, il che significa che per un malintenzionato è molto meno utile violare i server e che, in caso di violazione, le operazioni di pulizia sono molto più semplici.
- Le passkey offrono una protezione resistente al 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ù conveniente.
Implementa le passkey
Include la configurazione e le indicazioni per tutti i tipi di implementazione.
Configurazione
Imposta il livello API target su 35 nel file build.gradle del modulo dell'applicazione:
android { defaultConfig { targetSdk(35) } }Aggiungi le seguenti righe al file build.gradle della tua app o del tuo modulo, utilizzando l'ultima versione stabile del riferimento alle release
androidx.credentials.androidx.credentials:credentials:1.6.0 androidx.credentials:credentials-play-services-auth:1.6.0
Metodi di autenticazione integrati
Poiché Gestore delle credenziali è un'API unificata, i passaggi di implementazione per Wear OS sono gli stessi di qualsiasi altro tipo di dispositivo.
Utilizza le istruzioni per 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 per dispositivi mobili, ma sono gli stessi su Wear OS.
Tieni presente che, poiché non è possibile creare credenziali su Wear OS, non è necessario implementare i metodi di creazione delle credenziali menzionati nelle istruzioni per dispositivi mobili.
Metodi di autenticazione di backup
Esistono altri due metodi di autenticazione accettabili per le app per Wear OS: OAuth 2.0 (entrambe le varianti) e la condivisione del livello dati dei token di autenticazione mobile. Sebbene questi metodi non abbiano punti di integrazione nell'API Credential Manager, possono essere inclusi nel flusso UX di Gestore delle credenziali come opzioni di riserva nel caso in cui gli utenti chiudano la schermata di Gestore delle credenziali.
Per gestire l'azione dell'utente di chiudere la schermata di Gestore delle credenziali, intercetta un'eccezione GetCredentialCancellationException nell'ambito della logica GetCredential e vai alla tua UI di autenticazione personalizzata.
try { val getCredentialResponse: GetCredentialResponse = credentialManager.getCredential(activity, createGetCredentialRequest()) return authenticate(getCredentialResponse.credential) } catch (_: GetCredentialCancellationException) { navigateToSecondaryAuthentication() }
La tua UI di autenticazione personalizzata può quindi fornire uno qualsiasi degli altri metodi di autenticazione accettabili descritti nella guida alla UX di accesso.
Condivisione dei token del livello dati
L'app complementare per smartphone può trasferire in modo sicuro i dati di autenticazione all'app per Wear OS utilizzando l'API Wearable Data Layer. Trasferisci le credenziali come messaggi o come elementi dati.
In genere, questo tipo di autenticazione non richiede alcuna azione da parte dell'utente. Tuttavia, evita di eseguire l'autenticazione senza informare l'utente che sta eseguendo l'accesso. Puoi informare l'utente utilizzando una schermata ignorabile che mostra che il suo account è in fase di trasferimento da dispositivo mobile.
Importante: l'app per Wear OS deve offrire almeno un altro metodo di autenticazione, perché questa opzione funziona solo sugli smartwatch accoppiati con Android quando è installata l'app mobile corrispondente. Fornisci un metodo di autenticazione alternativo per gli utenti che non hanno l'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 putDataReq: PutDataRequest = PutDataMapRequest.create("/auth").run { dataMap.putString("token", token) asPutDataRequest() } val putDataTask: Task<DataItem> = Wearable.getDataClient(this).putDataItem(putDataReq)
Ascolta gli eventi di modifica dei dati nell'app per Wear OS, come mostrato nell'esempio seguente:
class AuthDataListenerService : WearableListenerService() { override fun onDataChanged(dataEvents: DataEventBuffer) { 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. handleSignInSequence(token) } } } } /** placeholder sign in handler. */ fun handleSignInSequence(token: String?) {} }
Per ulteriori informazioni sull'utilizzo del livello dati indossabile, consulta Invia e sincronizza i dati su Wear OS.
Utilizza 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 in RFC 7636
- Device Authorization Grant (DAG), come definito nella RFC 8628
Proof Key for Code Exchange (PKCE)
Per utilizzare efficacemente PKCE, utilizza RemoteAuthClient.
Poi, per eseguire una richiesta di autenticazione dalla tua app per 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 codice seguente mostra un esempio di creazione di una richiesta di autenticazione:
val oauthRequest = OAuthRequest.Builder(context) .setAuthProviderUrl(uri) .setCodeChallenge(codeChallenge) .setClientId(CLIENT_ID) .build()
Dopo aver creato la richiesta di autenticazione, inviala all'app complementare utilizzando il metodo sendAuthorizationRequest():
RemoteAuthClient.create(context).sendAuthorizationRequest( request = oauthRequest, executor = { command -> command?.run() }, clientCallback = object : RemoteAuthClient.Callback() { override fun onAuthorizationResponse( request: OAuthRequest, response: OAuthResponse ) { // Extract the token from the response, store it, and use it in requests. continuation.resume(parseCodeFromResponse(response)) } override fun onAuthorizationError(request: OAuthRequest, errorCode: Int) { // Handle Errors continuation.resume(Result.failure(IOException("Authorization failed"))) } } )
Questa richiesta attiva una chiamata all'app complementare, che poi presenta un'interfaccia utente di autorizzazione in un browser web sullo smartphone dell'utente. Il provider 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 l'aspetto di uno dei seguenti esempi:
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
In questo modo viene caricata una pagina che indirizza l'utente all'app complementare. L'app complementare verifica l'URL di risposta e lo inoltra all'app per Wear OS utilizzando l'API onAuthorizationResponse.
L'app dell'orologio può quindi scambiare il codice di autorizzazione con un token di accesso.
Device Authorization Grant
Quando utilizzi la concessione dell'autorizzazione del dispositivo, l'utente apre l'URI di verifica su un altro dispositivo. Il server di autorizzazione chiede quindi 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. private fun verifyDeviceAuthGrant(verificationUri: String) { RemoteActivityHelper(context).startRemoteActivity( Intent(Intent.ACTION_VIEW).apply { addCategory(Intent.CATEGORY_BROWSABLE) data = Uri.parse(verificationUri) }, null ) }
Se hai un'app per iOS, utilizza i link universali per intercettare questo intent nella tua app anziché affidarti al browser per autorizzare il token.