Autenticare gli utenti con Accedi con Google

Accedi con Google ti consente di integrare rapidamente l'autenticazione degli utenti con la tua app per Android. Gli utenti possono utilizzare il proprio Account Google per accedere alla tua app, fornire il consenso e condividere in modo sicuro le informazioni del proprio profilo con la tua app. La libreria Jetpack Credential Manager di Android semplifica questa integrazione, offrendo un'esperienza coerente su tutti i dispositivi Android utilizzando una singola API.

Questo documento illustra la procedura per implementare Accedi con Google nelle app Android, come configurare l'interfaccia utente del pulsante Accedi con Google e come configurare esperienze di registrazione e accesso One Tap ottimizzate per le app. Per una migrazione agevole dei dispositivi, Accedi con Google supporta l'accesso automatico e la sua natura cross-platform su Android, iOS e piattaforme web ti consente di fornire l'accesso per l'accesso alla tua app su qualsiasi dispositivo.

Per configurare Accedi con Google, segui questi due passaggi principali:

Configurare Accedi con Google come opzione per l'interfaccia utente del riquadro inferiore di Gestore delle credenziali. Questo può essere configurato in modo che all'utente venga chiesto di accedere automaticamente. Se hai implementato le passkey o le password, puoi richiedere contemporaneamente tutti i tipi di credenziali pertinenti, in modo che l'utente non debba ricordare l'opzione utilizzata in precedenza per accedere.

Riquadro inferiore di Gestore delle credenziali
Figura 1. Interfaccia utente di selezione delle credenziali del riquadro inferiore del Gestore delle credenziali

Aggiungi il pulsante Accedi con Google all'interfaccia utente dell'app. Il pulsante Accedi con Google offre agli utenti un modo semplificato per utilizzare i propri Account Google esistenti per registrarsi o accedere alle app per Android. Gli utenti faranno clic sul pulsante Accedi con Google se chiudono l'interfaccia utente del riquadro in basso o se vogliono utilizzare esplicitamente il proprio Account Google per la registrazione e l'accesso. Per gli sviluppatori, ciò significa un onboarding più semplice per gli utenti e una riduzione delle difficoltà durante la registrazione.

Animazione che mostra il flusso di Accedi con Google
Figura 2. Interfaccia utente del pulsante Accedi con Google di Gestore delle credenziali

Questo documento spiega come integrare il pulsante Accedi con Google e la finestra di dialogo del riquadro inferiore con l'API Gestore delle credenziali utilizzando la libreria di assistenza GoogleID.

Configura il progetto della console API di Google

  1. Apri il progetto nella console API o creane uno se non ne hai già uno.
  2. Nella pagina della schermata di consenso OAuth, assicurati che tutte le informazioni siano complete e accurate.
    1. Assicurati che all'app siano assegnati un nome, un logo e una home page corretti. Questi valori verranno mostrati agli utenti nella schermata del consenso di Accedi con Google al momento della registrazione e nella schermata App e servizi di terze parti.
    2. Assicurati di aver specificato gli URL delle norme sulla privacy e dei Termini di servizio della tua app.
  3. Nella pagina Credenziali, crea un ID client Android per la tua app se non ne hai già uno. Dovrai specificare il nome del pacchetto e la firma SHA-1 della tua app.
    1. Vai alla pagina Credenziali.
    2. Fai clic su Crea credenziali > ID client OAuth.
    3. Seleziona il tipo di applicazione Android.
  4. Nella pagina Credenziali, crea un nuovo ID client "App web" se non lo hai già fatto. Per il momento puoi ignorare i campi "Origini JavaScript autorizzate" e "URI di reindirizzamento autorizzati". Questo ID client verrà utilizzato per identificare il server di backend quando comunica con i servizi di autenticazione di Google.
    1. Vai alla pagina Credenziali.
    2. Fai clic su Crea credenziali > ID client OAuth.
    3. Seleziona il tipo di applicazione web.

Dichiarare le dipendenze

Nel file build.gradle del modulo, dichiara le dipendenze utilizzando la versione più recente di Credential Manager:

dependencies {
  // ... other dependencies

  implementation "androidx.credentials:credentials:<latest version>"
  implementation "androidx.credentials:credentials-play-services-auth:<latest version>"
  implementation "com.google.android.libraries.identity.googleid:googleid:<latest version>"
}

Crea un'istanza di una richiesta di accesso con Google

Per iniziare l'implementazione, inizializza una richiesta di accesso con Google. Utilizza GetGoogleIdOption per recuperare il token ID Google di un utente.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Innanzitutto, controlla se l'utente ha account che sono stati utilizzati in precedenza per accedere alla tua app chiamando l'API con il parametro setFilterByAuthorizedAccounts impostato su true. Gli utenti possono scegliere tra gli account disponibili per accedere.

Se non sono disponibili Account Google autorizzati, all'utente dovrebbe essere chiesto di registrarsi con uno dei suoi account disponibili. Per farlo, chiedi all'utente di chiamare di nuovo l'API e impostare setFilterByAuthorizedAccounts su false. Scopri di più sulla registrazione.

Attivare l'accesso automatico per gli utenti di ritorno (opzione consigliata)

Gli sviluppatori devono attivare l'accesso automatico per gli utenti che si registrano con il loro singolo account. In questo modo, viene offerta un'esperienza fluida su più dispositivi, in particolare durante la migrazione del dispositivo, in cui gli utenti possono recuperare rapidamente l'accesso al proprio account senza dover reinserire le credenziali. Per gli utenti, questo rimuove le difficoltà non necessarie se hanno già eseguito l'accesso in precedenza.

Per attivare l'accesso automatico, usa setAutoSelectEnabled(true). L'accesso automatico è possibile solo se vengono soddisfatti i seguenti criteri:

  • Esiste una singola credenziale corrispondente alla richiesta, che può essere un Account Google o una password, e questa credenziale corrisponde all'account predefinito sul dispositivo Android.
  • L'utente non si è disconnesso esplicitamente.
  • L'utente non ha disattivato l'accesso automatico nelle impostazioni dell'Account Google.
val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Ricorda di gestire correttamente l'uscita quando implementi l'accesso automatico, in modo che gli utenti possano sempre scegliere l'account corretto dopo aver eseguito esplicitamente l'uscita dalla tua app.

Impostare un nonce per migliorare la sicurezza

Per migliorare la sicurezza di accesso ed evitare attacchi di replay, aggiungi setNonce per includere un nonce in ogni richiesta. Scopri di più sulla generazione di un nonce.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Creare il flusso Accedi con Google

I passaggi per configurare un flusso di Accedi con Google sono i seguenti:

  1. Istanza un GetCredentialRequest, quindi aggiungi il googleIdOption creato in precedenza utilizzando addCredentialOption() per recuperare le credenziali.
  2. Passa questa richiesta alla chiamata getCredential() (Kotlin) o getCredentialAsync() (Java) per recuperare le credenziali disponibili dell'utente.
  3. Una volta che l'API è stata eseguita correttamente, estrai CustomCredential che contiene il risultato per i dati GoogleIdTokenCredential.
  4. Il tipo di CustomCredential deve essere uguale al valore di GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL. Converti l'oggetto in un GoogleIdTokenCredential utilizzando il metodo GoogleIdTokenCredential.createFrom.

  5. Se la conversione va a buon fine, estrai l'ID GoogleIdTokenCredential, convalidalo e autentica la credenziale sul tuo server.

  6. Se la conversione non va a buon fine con un codice GoogleIdTokenParsingException, potresti dover aggiornare la versione della libreria Accedi con Google.

  7. Individua eventuali tipi di credenziali personalizzate non riconosciute.

val request: GetCredentialRequest = Builder()
  .addCredentialOption(googleIdOption)
  .build()

coroutineScope.launch {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    handleFailure(e)
  }
}

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {

    // Passkey credential
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse on your server to
      // validate and authenticate
      responseJson = credential.authenticationResponseJson
    }

    // Password credential
    is PasswordCredential -> {
      // Send ID and password to your server to validate and authenticate.
      val username = credential.id
      val password = credential.password
    }

    // GoogleIdToken credential
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract the ID to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
          // You can use the members of googleIdTokenCredential directly for UX
          // purposes, but don't use them to store or control access to user
          // data. For that you first need to validate the token:
          // pass googleIdTokenCredential.getIdToken() to the backend server.
          GoogleIdTokenVerifier verifier = ... // see validation instructions
          GoogleIdToken idToken = verifier.verify(idTokenString);
          // To get a stable account identifier (e.g. for storing user data),
          // use the subject ID:
          idToken.getPayload().getSubject()
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Attivare un flusso del pulsante Accedi con Google

Per attivare il flusso del pulsante Accedi con Google, utilizza GetSignInWithGoogleOption anziché GetGoogleIdOption:

val signInWithGoogleOption: GetSignInWithGoogleOption = GetSignInWithGoogleOption.Builder()
  .setServerClientId(WEB_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Gestisci GoogleIdTokenCredential restituito come descritto nell'esempio di codice che segue.

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      }
      else -> {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Dopo aver creato l'istanza della richiesta di accesso con Google, avvia il flusso di autenticazione in modo simile a quanto indicato nella sezione Accedi con Google.

Attivare la registrazione per i nuovi utenti (opzione consigliata)

Accedi con Google è il modo più semplice per consentire agli utenti di creare un nuovo account con la tua app o il tuo servizio in pochi tocchi.

Se non vengono trovate credenziali salvate (nessun Account Google restituito da getGoogleIdOption), chiedi all'utente di registrarsi. Innanzitutto, controlla se esistono account utilizzati in precedenza.setFilterByAuthorizedAccounts(true) Se non ne viene trovato nessuno, chiedi all'utente di registrarsi con il suo Account Google utilizzando setFilterByAuthorizedAccounts(false)

Esempio:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(WEB_CLIENT_ID)
  .build()

Dopo aver creato l'istanza della richiesta di registrazione a Google, avvia il flusso di autenticazione. Se gli utenti non vogliono utilizzare Accedi con Google per la registrazione, ti consigliamo di ottimizzare la tua app per la compilazione automatica. Una volta che l'utente ha creato un account, valuta la possibilità di registrarlo alle passkey come passaggio finale della creazione dell'account.

Gestire la disconnessione

Quando un utente esce dalla tua app, chiama il metodo clearCredentialState() dell'API per cancellare lo stato delle credenziali dell'utente corrente da tutti i fornitori di credenziali. In questo modo, tutti i fornitori di credenziali verranno informati che è necessario cancellare eventuali sessioni di credenziali memorizzate per la determinata app.

Un provider di credenziali potrebbe aver memorizzato una sessione di credenziali attiva e utilizzarla per limitare le opzioni di accesso per le future chiamate get-credential. Ad esempio, potrebbe dare la priorità alla credenziale attiva rispetto a qualsiasi altra credenziale disponibile. Quando l'utente esce esplicitamente dalla tua app e per visualizzare le opzioni di accesso holistic la volta successiva, devi chiamare questa API per consentire al fornitore di cancellare qualsiasi sessione di credenziali memorizzata.