Implementare Accedi con Google

Questa guida descrive come implementare Accedi con Google e illustra i seguenti passaggi:

  • Aggiungi dipendenze alla tua app.
  • Crea un'istanza di CredentialManager.
  • Crea il flusso del riquadro inferiore.
  • Crea il flusso del pulsante.
  • Gestisci la risposta di accesso.
  • Gestisci gli errori.
  • Gestisci la disconnessione.

Aggiungi dipendenze alla tua app

Nel file build.gradle del modulo, dichiara le dipendenze utilizzando l'ultima versione di Gestore delle credenziali, Play Services Auth e googleid:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
    implementation("com.google.android.libraries.identity.googleid:googleid:<latest version>")
}

Trendy

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

Crea un'istanza di Gestore delle credenziali

Utilizza il contesto dell'app o dell'attività per creare un oggetto CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Crea il flusso del riquadro inferiore

Il riquadro inferiore è l'interfaccia utente integrata di Gestore delle credenziali. L'utilizzo di questa UI crea un'esperienza coerente in tutti i metodi di autenticazione, come password, passkey e Accedi con Google.

Configura la richiesta di accesso per gli account autorizzati in precedenza

Prova a effettuare una richiesta di accesso con Google con GetGoogleIdOption per recuperare il token ID Google dell'utente.

I seguenti snippet controllano se l'account è un account autorizzato.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setAutoSelectEnabled(true)
    .setNonce(generateSecureRandomNonce())
    .build()

L'oggetto della richiesta googleIdOption è configurato come segue:

  • Filtra gli account autorizzati in precedenza:per recuperare gli account autorizzati che sono stati utilizzati in precedenza per accedere alla tua app, imposta setFilterByAuthorizedAccounts su true.

    Tieni presente che il valore predefinito per setFilterByAuthorizedAccounts è true, il che significa che il comportamento predefinito per la UI del riquadro inferiore è mostrare solo gli account autorizzati in precedenza.

  • Imposta l'ID client del server:imposta il parametro setServerClientId. webClientId è l'ID client web che hai configurato per OAuth nel tuo progetto Google Cloud durante il completamento dei prerequisiti.

  • (Facoltativo) Attiva l'accesso automatico: per attivare l'accesso automatico per gli utenti di ritorno, utilizza setAutoSelectEnabled(true) e setFilterByAuthorizedAccounts(true). Per gli utenti della tua app, questo rimuove gli attriti non necessari se avevano già eseguito l'accesso in precedenza.

    L'accesso automatico è possibile solo se vengono soddisfatti i seguenti criteri:

    • Sul dispositivo è presente un solo account autorizzato, che è stato utilizzato in precedenza per accedere all'app sul dispositivo. La presenza di più account autorizzati sul dispositivo disattiva l'accesso automatico.
    • L'utente non è uscito esplicitamente dall'app durante la sessione precedente.
    • L'utente non ha disattivato l'accesso automatico nelle impostazioni dell'Account Google.

  • Imposta un nonce (facoltativo): per attivare la sicurezza avanzata, imposta un nonce per la verifica lato server. Per evitare attacchi di replay, puoi includere un nonce per la verifica lato server con setNonce(). Assicurati che il codice lato server convalidi che i nonce della richiesta e della risposta siano identici.

    Per generare il nonce, utilizza una funzione simile alla seguente che genera un nonce casuale crittograficamente sicuro di una lunghezza specificata e lo codifica utilizzando Base64:

fun generateSecureRandomNonce(byteLength: Int = 32): String {
    val randomBytes = ByteArray(byteLength)
    SecureRandom().nextBytes(randomBytes)
    return Base64.encodeToString(randomBytes, Base64.NO_WRAP or Base64.URL_SAFE or Base64.NO_PADDING)
}

Richiedi accesso

Controlla se l'utente ha un account autorizzato sul dispositivo chiamando il metodo getCredential:

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

// Use an activity-based context to avoid undefined system UI
// launching behavior.
val mutableContext = MutableContextWrapper(activityContext)
coroutineScope {
    try {
        val result = credentialManager.getCredential(
            request = request,            
            context = mutableContext // Use MutableContextWrapper to avoid memory leak during configuration changes
        )
        handleSignIn(result)
    } catch (e: GetCredentialException) {
        // Handle failures
    }
}

Configura la richiesta di accesso se non sono disponibili account autorizzati

Se non sono presenti utenti autorizzati per la tua app sul dispositivo, CredentialManager restituisce un NoCredentialException. In questo scenario, disattiva il filtro degli account autorizzati in modo che l'utente possa utilizzare un altro account per registrarsi.

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

Successivamente, richiedi l'accesso in modo simile a come hai fatto per gli account autorizzati.

Crea il flusso del pulsante

Utilizza un pulsante se vuoi che gli utenti possano accedere con Google per le seguenti condizioni:

  • L'utente ha ignorato la UI del riquadro inferiore di Gestore delle credenziali.
  • Non sono presenti Account Google sul dispositivo.
  • Gli account esistenti sul dispositivo richiedono la riautenticazione.

Crea la UI del pulsante

Anche se questa operazione può essere eseguita con un pulsante Jetpack Compose, puoi utilizzare un'icona del brand preapprovata dalla pagina Linee guida per il branding di Accedi con Google.

Crea il flusso di accesso

Crea una richiesta di accesso con Google con GetSignInWithGoogleOption per recuperare un token ID Google.

val signInWithGoogleOption: GetSignInWithGoogleOption = GetSignInWithGoogleOption.Builder(
    serverClientId = WEB_CLIENT_ID
).setNonce(generateSecureRandomNonce())
    .build()

Successivamente, richiedi l'accesso in modo simile a come hai fatto per l'interfaccia utente del riquadro inferiore.

Crea la funzione di accesso condiviso per il riquadro inferiore e il pulsante

Per gestire l'accesso, completa i seguenti passaggi:

  1. Utilizza la funzione getCredential() di CredentialManager. Se la risposta ha esito positivo, estrai CustomCredential, che deve essere di tipo GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL.

  2. Converti l'oggetto in un GoogleIdTokenCredential utilizzando il metodo GoogleIdTokenCredential.createFrom().

  3. Convalida la credenziale sul server della relying party.

  4. Assicurati di gestire gli errori in modo appropriato.

fun handleSign(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 the ID for server-side validation.
                    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")
        }
    }
}

Gestisci gli errori

Esamina gli errori elencati in Risoluzione dei problemi per assicurarti che il codice gestisca tutti i possibili scenari di errore.

Gestisci la disconnessione

È importante fornire agli utenti un meccanismo per uscire dalla tua app. Ad esempio, un utente potrebbe avere più Account Google sul dispositivo e decidere di accedere da un altro account. Puoi fornirlo, ad esempio, nella pagina delle impostazioni.

Un provider di credenziali potrebbe memorizzare una sessione di credenziali attiva e utilizzarla per limitare le opzioni di accesso per le richieste di accesso future. Ad esempio, può dare la priorità alla credenziale attiva rispetto a qualsiasi altra credenziale disponibile.

Quando un utente esce dalla tua app, chiama il metodo API clearCredentialState() per cancellare lo stato attuale delle credenziali utente da tutti i provider di credenziali. In questo modo, tutti i provider di credenziali verranno informati che tutte le sessioni di credenziali memorizzate per l'app in questione devono essere cancellate, offrendo agli utenti opzioni di accesso complete la volta successiva.