Le app Wear OS possono essere eseguite in modo autonomo, senza un'app complementare. Ciò significa che un'app 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 limitate riducono le opzioni di autenticazione che un'app Wear OS può utilizzare.
Questa guida fornisce istruzioni per il metodo di autenticazione consigliato per le app Wear OS, ovvero Credential Manager.
Per scoprire di più su come progettare una buona esperienza di accesso, 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à. 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 conoscere le funzionalità che 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 che eseguono 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 si toglie il dispositivo dal polso, il sistema lo mantiene sbloccato per un periodo di tempo più lungo del normale.
Se la tua app richiede un livello di sicurezza più elevato, ad esempio quando mostra dati potenzialmente sensibili o privati, controlla prima se il rilevamento del polso è attivato:
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
Gestore delle credenziali è l'API consigliata per l'autenticazione su Wear OS. Fornisce un ambiente più sicuro per consentire agli utenti di accedere alle applicazioni Wear OS in un'impostazione autonoma, senza la necessità di uno smartphone accoppiato e senza dover ricordare la password.
Questo documento descrive le informazioni necessarie agli sviluppatori per implementare una soluzione di Credential Manager con i meccanismi di autenticazione standard che ospita, ovvero:
- Passkey
- Password
- Identità federate (ad esempio Accedi con Google)
Questa guida fornisce anche istruzioni 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 istruzioni speciali per gestire la transizione dal pulsante Accedi con Google autonomo, ora ritirato, alla versione incorporata di Gestore delle credenziali.
Passkey su Wear OS
Gli sviluppatori sono vivamente incoraggiati a implementare le passkey nelle implementazioni di Credential Manager 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 devono digitare un nome utente.
- Gli utenti possono autenticarsi utilizzando il blocco schermo del dispositivo.
- Una volta creata e registrata una passkey, l'utente può passare facilmente a un nuovo dispositivo e utilizzarlo immediatamente senza dover eseguire una nuova 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 vantaggioso hackerare i server e che in caso di violazione è necessario eseguire molte meno operazioni di pulizia.
- 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 per la tua app o il tuo modulo, utilizzando l'ultima versione stabile del riferimento
androidx.credentials.androidx.credentials:credentials:1.5.0 androidx.credentials:credentials-play-services-auth:1.5.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 indicazioni per il mobile 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 pensati per lo sviluppo mobile, ma sono gli stessi su Wear OS. Consulta la sezione Transizione dall'accesso con Google legacy per considerazioni speciali per questo caso.
Tieni presente che, poiché non è possibile creare credenziali su Wear OS, non devi implementare i metodi di creazione delle credenziali menzionati nelle istruzioni per il mobile.
Metodi di autenticazione di backup
Esistono altri due metodi di autenticazione accettabili per le app Wear OS: OAuth 2.0 (in entrambe le varianti) e la condivisione del livello di dati del token di autenticazione mobile. Sebbene questi metodi non abbiano punti di integrazione nell'API Credential Manager, possono essere inclusi nel flusso UX di Credential Manager come fallback nel caso in cui gli utenti chiudano la schermata di Credential Manager.
Per gestire l'azione utente di chiusura della schermata di Credential Manager, intercetta un
NoCredentialException come parte della logica
GetCredential
e vai alla tua UI di autenticazione personalizzata.
yourCoroutineScope.launch {
try {
val response = credentialManager.getCredential(activity, request)
signInWithCredential(response.credential)
} catch (e: GetCredentialCancellationException) {
navigateToFallbackAuthMethods()
}
}
La tua UI di autenticazione personalizzata può quindi fornire uno qualsiasi degli altri metodi di autenticazione accettabili descritti nella guida all'esperienza utente di accesso.
Condivisione dei token del livello dati
L'app complementare per smartphone può trasferire in modo sicuro 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 chiudibile che mostra che il suo account viene trasferito 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 l'app mobile corrispondente è installata. 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.
Trasferisci 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)
Ascolta 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 indossabile, vedi 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 nella RFC 7636
- Device Authorization Grant (DAG), come definito nel documento RFC 8628
Proof Key for Code Exchange (PKCE)
Per utilizzare in modo efficace PKCE, utilizza RemoteAuthClient.
Poi, 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 al tuo endpoint OAuth per ottenere un token e da un
oggetto CodeChallenge.
Il seguente codice mostra un esempio di creazione di una richiesta di autorizzazione:
val request = OAuthRequest.Builder(this.applicationContext)
.setAuthProviderUrl(Uri.parse("https://...."))
.setClientId(clientId)
.setCodeChallenge(codeChallenge)
.build()
Dopo aver creato la richiesta di autorizzazione, 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 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
Viene caricata una pagina che indirizza l'utente all'app complementare. L'app complementare
verifica l'URL di risposta e inoltra la risposta alla tua app Wear OS
utilizzando l'API onAuthorizationResponse.
L'app per lo smartwatch può quindi scambiare il codice di autorizzazione con un token di accesso.
Concessione dell'autorizzazione del dispositivo
Quando si utilizza la concessione di 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.
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 intent nella tua app anziché fare affidamento sul browser per autorizzare il token.
Eseguire la transizione dall'accesso con Google legacy
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 Credential Manager, la vecchia opzione è ora ritirata.
// 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+")
}
)