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.6.0")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0")
    implementation("com.google.android.libraries.identity.googleid:googleid:<latest version>")
}

Trendy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0"
    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 Credential Manager. L'utilizzo di questa UI crea un'esperienza coerente per 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 utilizzati in precedenza per accedere alla tua app, imposta setFilterByAuthorizedAccounts su true.

Tieni presente che il valore predefinito di setFilterByAuthorizedAccounts è true, il che implica che il comportamento predefinito dell'interfaccia utente del riquadro inferiore è di 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.
Attiva l'accesso automatico (facoltativo): per attivare l'accesso automatico per gli utenti che ritornano, utilizza setAutoSelectEnabled(true) e setFilterByAuthorizedAccounts(true). Per gli utenti della tua app, questo elimina inutili attriti 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 e questo account autorizzato è stato utilizzato in precedenza per accedere all'app sul dispositivo. Più account autorizzati sul dispositivo disabilitano l'accesso automatico.
- L'utente non ha eseguito esplicitamente la disconnessione dall'app durante la sessione precedente.
- L'utente non ha disattivato l'accesso automatico nelle impostazioni del proprio Account Google .
Imposta un nonce (facoltativo): per attivare la sicurezza avanzata, imposta un nonce per la verifica lato server. Per impedire gli attacchi di riproduzione, puoi includere un nonce per la verifica lato server con setNonce(). Assicurati che il codice lato server convalidi che i nonce di richiesta e 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)
}

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

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

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

Configura la richiesta di accesso se non sono disponibili account autorizzati

Se sul dispositivo non sono presenti utenti autorizzati per la tua app, 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()

Dopodiché, richiedi l'accesso in modo simile a quello degli 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 chiuso l'interfaccia utente del riquadro inferiore di Gestore delle credenziali.
Sul dispositivo non sono presenti Account Google.
Gli account esistenti sul dispositivo richiedono la riautenticazione.

Crea l'interfaccia utente del pulsante

Anche se puoi farlo con un pulsante Jetpack Compose, puoi utilizzare un'icona del brand preapprovata dalla pagina Linee guida per il branding di Accedi con Google.

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()

Dopodiché, richiedi l'accesso in modo simile a quello dell'interfaccia utente del riquadro inferiore.

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

Per gestire l'accesso, svolgi i seguenti passaggi:

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.
Converti l'oggetto in un GoogleIdTokenCredential utilizzando il metodo GoogleIdTokenCredential.createFrom().

Nota: se la conversione non riesce con un GoogleIdTokenParsingException, allora potresti dover aggiornare la versione della libreria Accedi con Google.
Convalida la credenziale sul server del componente.
Assicurati di gestire gli errori in modo appropriato.

Nota: prima di considerare attendibile il token ID che ricevi per consentire all'utente di accedere alla tua app, devi convalidarne l'autenticità. Per verificare il token, invia googleIdTokenCredential.getIdToken() al tuo server. Per ulteriori informazioni sulla convalida lato server, consulta Convalidare il token ID Google lato server.

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 nella sezione Risoluzione dei problemi per assicurarti che il codice gestisca tutti i possibili scenari di errore.

Gestisci la disconnessione

È importante fornire un meccanismo per consentire agli utenti di disconnettersi dalla tua app. Ad esempio, un utente potrebbe avere più Account Google sul dispositivo e decidere di accedere da un altro account. Puoi fornire questa opzione, 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 si disconnette dalla tua app, chiama il metodo API clearCredentialState() per cancellare lo stato delle credenziali dell'utente corrente da tutti i provider di credenziali. In questo modo, tutti i provider di credenziali verranno informati che qualsiasi sessione di credenziali memorizzata per la determinata app deve essere cancellata, fornendo agli utenti tutte le opzioni di accesso la volta successiva.