Autenticare gli utenti con Accedi con Google

Accedi con Google ti aiuta a 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 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 ti guida nell'implementazione di Accedi con Google nelle app per Android, nella configurazione dell'interfaccia utente del pulsante Accedi con Google e nella configurazione di esperienze di registrazione e accesso One Tap ottimizzate per le app. Per una migrazione fluida dei dispositivi, Accedi con Google supporta l'accesso automatico e la sua natura multipiattaforma su Android, iOS e web ti aiuta a fornire l'accesso alla tua app su qualsiasi dispositivo. Se utilizzi Firebase Authentication per la tua applicazione, puoi scoprire di più sull'integrazione di Accedi con Google e Credential Manager nella guida Eseguire l'autenticazione con Google su Android.

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

Configura Accedi con Google come opzione per la UI del foglio inferiore di Credential Manager. Può essere configurato in modo da richiedere automaticamente all'utente di accedere. Se hai implementato passkey o 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. Il foglio inferiore del Gestore delle credenziali Interfaccia utente di selezione delle credenziali

Aggiungi il pulsante Accedi con Google all'interfaccia utente della tua app. Il pulsante Accedi con Google offre agli utenti un modo semplice 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 foglio inferiore o se vogliono utilizzare esplicitamente il proprio Account Google per la registrazione e l'accesso. Per gli sviluppatori, ciò significa un onboarding più semplice degli utenti e una riduzione delle difficoltà durante la registrazione.

Animazione che mostra il flusso di Accedi con Google
Figura 2. UI 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 foglio inferiore con l'API Credential Manager utilizzando la libreria helper Google ID.

Configura il progetto

  1. Apri il progetto in o creane uno se non ne hai già uno.
  2. Nella sezione , assicurati che tutte le informazioni siano complete e accurate.
    1. Assicurati che alla tua app siano assegnati un nome, un logo e una home page corretti. Questi valori verranno presentati agli utenti nella schermata del consenso di Accedi con Google durante la 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. In , 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 al .
    2. Fai clic su Crea cliente.
    3. Seleziona il tipo di applicazione Android.
  4. In , crea un nuovo ID client "Applicazione web" se non l'hai ancora 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 al .
    2. Fai clic su Crea cliente.
    3. Seleziona il tipo 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, crea un'istanza di 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)
  // nonce string to use when generating a Google ID token
  .setNonce(nonce)
.build()
SignInWithGoogleFunctions.kt

Innanzitutto, controlla se l'utente ha account 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 verrà 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 proprio account singolo. In questo modo, l'esperienza è fluida su tutti i dispositivi, soprattutto durante la migrazione dei dispositivi, quando gli utenti possono riaccedere rapidamente al proprio account senza reinserire le credenziali. Per i tuoi utenti, questo elimina inutili attriti quando avevano già eseguito l'accesso in precedenza.

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

  • Esiste una sola 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 ha eseguito la disconnessione in modo esplicito.
  • 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)
  // nonce string to use when generating a Google ID token
  .setNonce(nonce)
.build()
SignInWithGoogleFunctions.kt

Ricorda di gestire correttamente l'uscita quando implementi l'accesso automatico, in modo che gli utenti possano sempre scegliere l'account corretto dopo essere usciti esplicitamente 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)
  // nonce string to use when generating a Google ID token
  .setNonce(nonce)
.build()
SignInWithGoogleFunctions.kt

Creare il flusso Accedi con Google

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

  1. Crea un'istanza di GetCredentialRequest, quindi aggiungi 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 completata l'API, estrai CustomCredential che contiene il risultato per i dati GoogleIdTokenCredential.
  4. Il tipo per 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 ha esito positivo, estrai l'ID GoogleIdTokenCredential, convalidalo e autentica la credenziale sul tuo server.

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

  7. Rileva eventuali tipi di credenziali personalizzate non riconosciuti.

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

coroutineScope {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    // Handle failure
  }
}
SignInWithGoogleFunctions.kt


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

  when (credential) {

    // Passkey credential
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse to 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.
          // see [validation instructions](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token)
        } 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")
    }
  }
}
SignInWithGoogleFunctions.kt

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(
  serverClientId = WEB_CLIENT_ID
).setNonce(nonce)
  .build()
SignInWithGoogleFunctions.kt

Gestisci il GoogleIdTokenCredential restituito come descritto nell'esempio di codice seguente.

fun handleSignInWithGoogleOption(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")
    }
  }
}
SignInWithGoogleFunctions.kt

Una volta creata un'istanza della richiesta di accesso con Google, avvia il flusso di autenticazione in modo simile a quanto descritto nella sezione Accedi con Google.

Attiva la registrazione per i nuovi utenti (opzione consigliata)

Accedi con Google è il modo più semplice per gli 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. Per prima cosa, controlla se setFilterByAuthorizedAccounts(true) per vedere se esistono account utilizzati in precedenza. Se non ne viene trovato nessuno, invita l'utente a registrarsi con il proprio Account Google utilizzando setFilterByAuthorizedAccounts(false)

Esempio:

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

Una volta creata l'istanza della richiesta di registrazione con Google, avvia il flusso di autenticazione. Se gli utenti non vogliono utilizzare Accedi con Google per la registrazione, valuta la possibilità di ottimizzare la tua app per il riempimento automatico. Una volta creato un account, valuta la possibilità di registrare l'utente alle passkey come passaggio finale della creazione dell'account.

Gestire la disconnessione

Quando un utente esce dalla tua app, chiama il metodo API clearCredentialState() per cancellare lo stato delle credenziali dell'utente corrente da tutti i fornitori di credenziali. In questo modo, tutti i fornitori di credenziali verranno avvisati che qualsiasi sessione di credenziali memorizzata per l'app specificata deve essere cancellata.

Un fornitore 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 ottenere le opzioni di accesso olistico la volta successiva, devi chiamare questa API per consentire al provider di cancellare qualsiasi sessione di credenziali memorizzata.