Questa pagina è stata tradotta dall'API Cloud Translation.

Integra Gestore delle credenziali con Accedi con Google

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

Questo documento illustra come implementare la funzionalità Accedi con Google nelle app per Android, come configurare l'UI del pulsante Accedi con Google e come configurare esperienze di registrazione e accesso con un tocco ottimizzate per le app. Per una migrazione senza problemi dei dispositivi, Accedi con Google supporta l'accesso automatico e, grazie alla sua natura multipiattaforma su piattaforme Android, iOS e web, ti consente di accedere alla tua app su qualsiasi dispositivo.

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

Configura Accedi con Google come opzione per l'interfaccia utente nel foglio inferiore di Gestore delle credenziali. Questa opzione può essere configurata in modo da chiedere automaticamente all'utente di eseguire l'accesso. 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 che ha utilizzato in precedenza per accedere.

Riquadro inferiore di Gestore delle credenziali — **Figura 1.** L'interfaccia utente per la selezione delle credenziali nel foglio inferiore di Gestore delle credenziali

Aggiungi il pulsante Accedi con Google all'UI della tua app. Il pulsante Accedi con Google offre agli utenti un modo più semplice per usare i loro Account Google esistenti per registrarsi o accedere alle app per Android. Gli utenti faranno clic sul pulsante Accedi con Google se ignorano l'interfaccia utente nel riquadro inferiore o se vogliono utilizzare esplicitamente il proprio Account Google per registrarsi e accedere. Per gli sviluppatori, ciò significa onboarding più facile e meno problemi durante la registrazione.

Animazione che mostra il flusso 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 riquadro inferiore con l'API Credential Manager utilizzando la libreria helper Google ID.

Configura il progetto nella console delle API di Google

Apri il progetto nella console API o creane uno, se non ne hai già uno.
Nella pagina della schermata per il consenso OAuth, assicurati che tutte le informazioni siano complete e accurate.
1. Assicurati che alla tua app siano stati assegnati correttamente nome, logo e home page dell'app. Questi valori saranno mostrati agli utenti nella schermata per il 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 dell'app.
Nella pagina Credenziali, crea un ID client Android per la tua app, se non ne hai già uno. Dovrai specificare il nome del pacchetto dell'app e la firma SHA-1.
1. Vai alla pagina Credenziali.
2. Fai clic su Crea credenziali > ID client OAuth.
3. Seleziona il tipo di applicazione Android.
Nella pagina Credenziali, crea un nuovo ID client "Applicazione web" se non l'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.

Dichiara le dipendenze

Nel file build.gradle del tuo modulo, dichiara le dipendenze utilizzando la versione più recente di Gestore delle credenziali:

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>"
}

Creare l'istanza di una richiesta di accesso a Google

Per iniziare l'implementazione, instaura una richiesta di accesso a 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, verifica se l'utente dispone di 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 l'accesso.

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 chiamando di nuovo l'API e impostando setFilterByAuthorizedAccounts su false. Scopri di più sulla registrazione.

Gli sviluppatori dovrebbero abilitare l'accesso automatico per gli utenti che si registrano con il proprio account singolo. Questo offre un'esperienza fluida su tutti i dispositivi, soprattutto durante la migrazione dei dispositivi, dove gli utenti possono riottenere rapidamente l'accesso al proprio account senza reinserire le credenziali. Per i tuoi utenti, questo elimina gli attriti inutili quando avevano già effettuato l'accesso.

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

Esiste un'unica 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()

Ricordati 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 la disconnessione dall'app.

Imposta un nonce per migliorare la sicurezza

Per migliorare la sicurezza dell'accesso ed evitare attacchi di ripetizione, 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

Ecco i passaggi per configurare un flusso Accedi con Google:

Crea un'istanza di GetCredentialRequest, quindi aggiungi la googleIdOption creata in precedenza utilizzando addCredentialOption() per recuperare le credenziali.
Passa questa richiesta alla chiamata getCredential() (Kotlin) o getCredentialAsync() (Java) per recuperare le credenziali disponibili dell'utente.
Una volta che l'API ha esito positivo, estrai il campo CustomCredential che contiene il risultato dei dati di GoogleIdTokenCredential.
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.
Se la conversione ha esito positivo, estrai l'ID GoogleIdTokenCredential, convalidalo e autentica la credenziale sul tuo server.
Se la conversione non va a buon fine con un token GoogleIdTokenParsingException, potresti dover aggiornare la versione della libreria Accedi con Google.
Individuare i tipi di credenziali personalizzate non riconosciuti.

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 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 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 il valore GoogleIdTokenCredential restituito come descritto nell'esempio di codice riportato di seguito.

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 un'istanza della richiesta di accesso a Google, avvia il flusso di autenticazione in modo simile a quanto indicato nella sezione Accedi con Google.

Accedi con Google è il modo più semplice in cui gli utenti possono 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 setFilterByAuthorizedAccounts(true) per vedere se esistono account utilizzati in precedenza. Se non ne trova, chiedi all'utente di registrarsi con il proprio Account Google utilizzando setFilterByAuthorizedAccounts(false)

Esempio:

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

Dopo aver creato un'istanza della richiesta di registrazione a Google, avvia il flusso di autenticazione. Se gli utenti non vogliono registrarsi con Google, prendi in considerazione i servizi di compilazione automatica o le passkey per la creazione dell'account.

Gestire l'uscita

Quando un utente si disconnette dalla tua app, chiama il metodo API clearCredentialState() per cancellare l'attuale stato delle credenziali utente da tutti i fornitori di credenziali. In questo modo, tutti i fornitori di credenziali comunicheranno che qualsiasi sessione di credenziali memorizzate per l'app in questione deve essere cancellata.

Un provider di credenziali potrebbe aver archiviato una sessione di credenziali attiva e utilizzarla per limitare le opzioni di accesso per le future chiamate con credenziali di recupero. Ad esempio, potrebbe dare la priorità alla credenziale attiva rispetto a qualsiasi altra credenziale disponibile. Quando l'utente esce esplicitamente dalla tua app e la prossima volta per usufruire delle opzioni di accesso olistiche, devi chiamare questa API per consentire al provider di cancellare qualsiasi sessione di credenziali memorizzate.