Autenticazione su indossabili

Le app per Wear OS possono essere eseguite autonome, 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 e le capacità di immissione ridotte dell'orologio limitano le opzioni di autenticazione utilizzabili da un'app Wear OS.

Questa guida illustra i metodi di autenticazione consigliati per le app Wear OS, nonché le alternative, quando questi metodi non sono adatti al caso d'uso di un'app.

Per scoprire di più su come progettare una buona esperienza di accesso, consulta la guida all'esperienza utente per l'accesso.

Modalità Ospite

Non richiedere l'autenticazione per tutte le funzionalità. Fornisci invece il maggior numero possibile di funzionalità all'utente senza richiedere l'accesso.

Gli utenti potrebbero trovare e installare la tua app Wear senza aver utilizzato l'app mobile, quindi potrebbero non avere un account e potrebbero non sapere quali funzionalità offre. Assicurati che la funzionalità della modalità ospite mostri accuratamente le funzioni della tua app.

Metodi di autenticazione consigliati

Utilizza i seguenti metodi di autenticazione per consentire alle app Wear OS autonome di ottenere le credenziali di autenticazione degli utenti.

Passaggio dei token utilizzando il livello dati

L'app complementare per smartphone può trasferire in sicurezza i dati di autenticazione all'app Wear OS tramite il livello dati indossabile. Trasferisci le credenziali come messaggi o 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 ha eseguito l'accesso. Puoi informare l'utente utilizzando una semplice schermata ignorabile che mostra che il suo account viene trasferito da un dispositivo mobile.

Importante: l'app Wear deve offrire almeno un altro metodo di autenticazione, perché questa opzione funziona solo sugli orologi accoppiati con Android quando è installata l'app mobile corrispondente. Fornisci un metodo di autenticazione alternativo agli utenti che non hanno l'app mobile corrispondente o che hanno un 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 wearable 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 sull'app dell'orologio, 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 interstitial screen to notify the user they are being signed in.
                // Then, store the token and use it in network requests.
            }
        }
    }
}

Per maggiori informazioni sull'utilizzo del livello dati indossabile, consulta Inviare e sincronizzare 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 chiave di prova per lo scambio di codice (PKCE), come definito in RFC 7636
• Concessione di autorizzazione del dispositivo, come definita in RFC 8628

Nota:per assicurarti che la tua app non si spenga quando lo smartwatch passa in modalità Ambient, abilita Sempre attivo tramite AmbientModeSupport.attach nell'attività che esegue l'autenticazione. Per ulteriori informazioni sulle best practice relative alla modalità Ambient, consulta la pagina Mantenere visibile la tua app su Wear.

Codice comprovante lo scambio di codice (PKCE)

Per usare in modo efficace PKCE, usa RemoteAuthClient.

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 al tuo endpoint OAuth per ricevere un token e 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 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 error
        }
    }
)

Questa richiesta attiva una chiamata all'app complementare, che a sua volta presenta un'UI di autorizzazione in un browser web sul cellulare dell'utente. Il provider OAuth 2.0 autentica l'utente e ottiene il consenso dell'utente 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 ed è simile a 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 companion. L'app complementare verifica l'URL di risposta e inoltra la risposta all'app dell'orologio di terze parti utilizzando l'API onAuthorizationResponse.

L'app dell'orologio può quindi scambiare il codice di autorizzazione con un token di accesso.

Nota: una volta creato OAuthRequest, puoi trovare l'URL di reindirizzamento accedendo a redirectUrl.

Concessione di autorizzazione del dispositivo

Quando utilizza Concessione di autorizzazione del dispositivo, l'utente apre l'URI di verifica su un altro dispositivo. Poi, il server di autorizzazione chiede di approvare o rifiutare la richiesta.

Per semplificare questa procedura, usa 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 nell'app anziché affidarti al browser per autorizzare il token.

Altri metodi di autenticazione

Wear OS supporta metodi di accesso aggiuntivi, descritti nelle sezioni seguenti.

Accedi con Google

L'opzione Accedi con Google consente all'utente di accedere con il suo Account Google esistente. Offre la migliore esperienza utente ed è facile da supportare, soprattutto se la implementi già nelle tue app portatili.

Dopo i metodi di autenticazione consigliati descritti in precedenza, Accedi con Google è la seconda soluzione preferita, perché funziona bene anche su iOS. La seguente sezione descrive come completare un'integrazione di base di Accedi con Google.

Prerequisiti

Per poter iniziare a integrare la funzionalità Accedi con Google nella tua app per Wear OS, devi configurare un progetto della console API di Google e configurare il progetto Android Studio. Per maggiori informazioni, consulta la pagina Iniziare a integrare Accedi con Google nella tua app Android.

Se utilizzi Accedi con Google con un'app o un sito che comunica con un server di backend, sono previsti due prerequisiti aggiuntivi:

• Crea un ID client applicazione web OAuth 2.0 per il tuo server di backend. Questo ID client è diverso dall'ID client dell'app. Per maggiori informazioni, consulta Abilitare l'accesso lato server.
• Identifica in modo sicuro l'utente che ha eseguito l'accesso al server inviando il token ID dell'utente tramite HTTPS. Per scoprire come autenticare l'utente sul server di backend, consulta Autenticazione con un server di backend.

Integra Accedi con Google nella tua app

Esamina e implementa i passaggi seguenti, descritti in dettaglio nelle sezioni che seguono, per integrare Accedi con Google nella tua app Wear OS:

1. Configura Accedi con Google.
2. Aggiungi un pulsante Accedi con Google.
3. Avvia il flusso di accesso al tocco del pulsante di accesso.

Configurare Accedi con Google e creare l'oggetto GoogleApiClient

Nel metodo onCreate() dell'attività di accesso, configura Accedi con Google per richiedere i dati utente richiesti dalla tua app. Quindi, crea un oggetto GoogleApiClient con accesso all'API Accedi con Google e alle opzioni che hai specificato. Questi passaggi sono mostrati nell'esempio seguente:

  public class MyNewActivity extends AppCompatActivity {

    private static final int RC_SIGN_IN = 9001;

    private GoogleSignInClient mSignInClient;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        GoogleSignInOptions options =
               new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_SIGN_IN)
                        .build();

        mSignInClient = GoogleSignIn.getClient(this, options);
    }
  }

Aggiungere un pulsante Accedi con Google alla tua app

Completa i seguenti passaggi per aggiungere un pulsante Accedi con Google:

1. Aggiungi SignInButton al layout della tua app:

 <com.google.android.gms.common.SignInButton
 android:id="@+id/sign_in_button"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content" />

2. Nel metodo onCreate() dell'app, registra il OnClickListener del pulsante per far accedere l'utente quando viene toccato:

Kotlin

findViewById<View>(R.id.sign_in_button).setOnClickListener(this)

Java

findViewById(R.id.sign_in_button).setOnClickListener(this);

Crea un intent di accesso e avvia il flusso di accesso

Per gestire i tocchi dei pulsanti di accesso nel metodo onCLick(), crea un intent di accesso con il metodo getSignInIntent(). Quindi avvia l'intent con il metodo startActivityForResult().

  Intent intent = mSignInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);

The user is prompted to select a Google account to sign in with. If you requested scopes beyond profile, email, and open ID, the user is also prompted to grant access to those resources.

Finally, in the activity's onActivityResult method, retrieve the sign-in result with getSignInResultFromIntent. After you retrieve the sign-in result, you can check whether the sign-in succeeded using the isSuccess method. If sign-in succeeds, you can call the getSignInAccount method to get a GoogleSignInAccount object that contains information about the signed-in user, such as the user's name. These steps are shown in the following example:

Kotlin

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    super.onActivityResult(requestCode, resultCode, data)

    // Result returned from launching the Intent from GoogleSignInApi.getSignInIntent(...).
    if (requestCode == RC_SIGN_IN) {
        Auth.GoogleSignInApi.getSignInResultFromIntent(data)?.apply {
            if (isSuccess) {
                // Get account information.
                fullName = signInAccount?.displayName
                mGivenName = signInAccount?.givenName
                mFamilyName = signInAccount?.familyName
                mEmail = signInAccount?.email
            }
        }
    }
}

Java

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    // Result returned from launching the Intent from GoogleSignInApi.getSignInIntent(...).
    if (requestCode == RC_SIGN_IN) {
        GoogleSignInResult signInResult = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
        if (signInResult.isSuccess()) {
            GoogleSignInAccount acct = signInResult.getSignInAccount();

            // Get account information.
            fullName = acct.getDisplayName();
            givenName = acct.getGivenName();
            familyName = acct.getFamilyName();
            email = acct.getEmail();
        }
    }
}

Per visualizzare un'app di esempio che implementa Accedi con Google, consulta l' esempio di esempio di Accedi con Google per l'orologo su GitHub.

Autenticazione con codice personalizzato

In alternativa ai metodi di autenticazione descritti in precedenza, puoi richiedere all'utente di eseguire l'autenticazione da un altro dispositivo, ad esempio un cellulare o un tablet, e ottenere un codice numerico di breve durata. L'utente inserisce quindi il codice sul proprio dispositivo Wear OS per confermare la propria identità e riceve un token di autorizzazione.

Questo flusso di autenticazione utilizza il modulo di accesso dell'app oppure integra manualmente un metodo di accesso del provider di autenticazione di terze parti nel codice dell'app. Anche se questo metodo di autenticazione richiede operazioni manuali e sforzi aggiuntivi per renderlo più sicuro, puoi utilizzare questo metodo se hai bisogno dell'autenticazione in precedenza nelle app Wear OS autonome.

Il flusso di autenticazione per questa configurazione funziona come segue:

1. L'utente esegue un'azione con l'app Wear OS che richiede l'autorizzazione.
2. L'app per Wear OS presenta una schermata di autenticazione all'utente e invita l'utente a inserire un codice da un URL specificato.
3. L'utente passa a un dispositivo mobile, un tablet o un PC, quindi avvia un browser, va all'URL specificato nell'app Wear OS e esegue l'accesso.
4. L'utente riceve un codice numerico di breve durata da inserire nella schermata di autenticazione dell'app Wear OS utilizzando la tastiera integrata in Wear OS:

   

5. A questo punto, puoi utilizzare il codice inserito per dimostrare che si tratta dell'utente corretto e sostituirlo con un token di autenticazione archiviato e protetto sul dispositivo Wear OS per le chiamate autenticate in futuro.

Nota: il codice generato dall'utente deve essere puramente numerico e non può contenere caratteri alfabetici.

Questo flusso di autenticazione è illustrato nel seguente grafico: