Pacchetto di sicurezza

Questa guida descrive una raccolta di funzionalità che restituiscono ulteriori indicatori di affidabilità su un Account Google. Questi indicatori di affidabilità aiutano il tuo sistema di gestione degli account a prendere decisioni basate sul rischio durante la registrazione, la creazione di account e in seguito per gli utenti di ritorno.

Configurazione

Per ricevere ulteriori attestazioni, la tua app deve essere pubblicata, verificata e le funzionalità del bundle di sicurezza devono essere attivate.

Per verificare che la tua app sia pubblicata e verificata:

1. Apri Google Auth Platform.
2. Seleziona o crea il progetto per la tua app
3. Fai clic su Segmento di pubblico nel menu.
4. Verifica che lo Stato della pubblicazione sia In produzione.
5. Fai clic su Centro di verifica nel menu.

6. Verifica che lo stato della verifica sia Verificata.

   Per saperne di più, visita il Centro assistenza per la verifica delle app OAuth.

Per attivare la rivendicazione auth_time:

1. Apri Google Auth Platform.
2. Seleziona o crea il progetto per la tua app
3. Fai clic su Impostazioni nel menu.
4. In Impostazioni avanzate, seleziona Rivendicazioni relative all'età della sessione per attivare auth_time.

Funzionalità supportate

Questa sezione descrive le singole funzionalità che compongono il pacchetto di sicurezza.

auth_time

L'attestazione auth_time è una parte standard del protocollo OpenID Connect che fornisce informazioni sull'ultima autenticazione dell'utente finale con Google. È un numero JSON che rappresenta il numero di secondi trascorsi dall'epoca di Unix (1° gennaio 1970, 00:00:00 UTC) ed è l'ora dell'ultima autenticazione dell'utente. Consideralo come un timestamp che indica l'ultimo evento di accesso dell'utente al suo Account Google dal dispositivo o dal browser corrente. Questa rivendicazione è inclusa nel token ID, che è un token JWT (JSON Web Token) contenente informazioni verificate sull'autenticazione e sull'utente.

L'attestazione auth_time è utile per la tua applicazione perché ti consente di determinare la data dell'ultimo accesso attivo di un utente a un Account Google sul dispositivo o browser che sta utilizzando. Questo può essere particolarmente importante per motivi di sicurezza, ad esempio:

• Prendere una decisione informata in merito all'opportunità che la tua app emetta un'ulteriore richiesta di autenticazione avanzata prima di eseguire azioni utente sensibili come l'eliminazione dell'account, la modifica dei metodi di contatto dell'account o l'esecuzione di un pagamento. Google non supporta le richieste di riautenticazione dell'Account Google.

• Utilizzo della freschezza e della stabilità della sessione dell'Account Google dell'utente come indicatore di affidabilità. In generale, un valore di auth_time recente è un'indicazione di aggiornamento, mentre un valore precedente indica stabilità.

Per le app web, la combinazione del browser e del sistema operativo dell'utente costituisce una sessione dopo che l'utente ha eseguito l'accesso al proprio Account Google. In modo indipendente, il tuo sito web mantiene anche una sessione utente separata. Un valore auth_time più recente indica che l'utente ha eseguito l'accesso al proprio Account Google di recente. Spesso questo è un indicatore di un utente attivo e coinvolto e può essere interpretato come un segnale di rischio inferiore.

Sulle piattaforme mobile come Android, gli utenti in genere accedono direttamente al proprio dispositivo utilizzando metodi biometrici come la scansione dell'impronta o del volto e lo sblocco con PIN o sequenza specifici del dispositivo. Le app e le piattaforme mobile spesso utilizzano questi metodi di autenticazione basati sulla piattaforma anziché creare una nuova sessione con Google, il che comporta accessi infrequenti all'Account Google e aggiornamenti corrispondenti a auth_time. Pertanto, un valore auth_time recente potrebbe segnalare una modifica a una sessione dell'Account Google di lunga durata e quindi un aumento del rischio.

Gli indicatori di attendibilità sono un argomento complesso. auth_time dovrebbe essere utilizzato insieme ad altri indicatori, ad esempio se l'autenticazione a più fattori (MFA) è abilitata, il metodo di autenticazione utilizzato e la durata della sessione utente tra l'applicazione e la piattaforma.

Richiesta auth_time

Il metodo specifico utilizzato per richiedere l'attestazione auth_time varia a seconda dell'API utilizzata, ma ogni API include un parametro claims facoltativo per richiedere auth_time.

Attenzione: aggiornamento del 18/11/2025: è presente un problema noto con un valore auth_time errato restituito quando un singolo dispositivo o browser ha più sessioni utente attive. Le singole sessioni non sono interessate.

Protocollo OIDC

Quando utilizzi direttamente la piattaforma OAuth, richiedi auth_time aggiungendolo al parametro di richiesta delle rivendicazioni facoltative. Imposta il valore del campo id_token dell'oggetto JSON delle rivendicazioni su {"auth_time":{"essential":true}}. Ad esempio,

https://accounts.google.com/o/oauth2/v2/auth?
response_type=id_token&
client_id=YOUR_CLIENT_ID&
scope=openid email profile&
redirect_uri=https://example.com/user-login&
nonce=123-456-7890&
claims={"id_token":{"auth_time":{"essential":true}}}

Nota: sono stati aggiunti interruzioni di riga per migliorare la leggibilità. Il valore effettivo del parametro request and claims è JSON codificato tramite URL.

Per saperne di più, consulta OpenID Connect.

GIS per il web

La libreria Accedi con Google per il web ha due API: HTML e JavaScript per richiedere ulteriori rivendicazioni. Ad esempio, richiedi auth_time utilizzando l'API JavaScript:

<html>
<body>
  <script src="https://accounts.google.com/gsi/client" async></script>
  <script>
    window.onload = function () {
      google.accounts.id.initialize({
        client_id: "YOUR_WEB_CLIENT_ID",
        callback: function(rsp) { console.log(rsp.credential); },
        essential_claims: "auth_time",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

Per saperne di più, consulta la sezione Accedi con Google per il web.

GIS per Android

Per richiedere auth_time vengono utilizzati un metodo setClaims e un oggetto Claim.

Aggiorna le dipendenze della build per utilizzare le versioni più recenti delle librerie androidx.credentials:credentials-play-services-auth e com.google.android.libraries.identity.googleid:googleid.

Crea un'istanza di un oggetto Claim di tipo auth_time, utilizzando setClaims per aggiungere le opzioni di accesso:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setAutoSelectEnabled(true)
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setNonce("NONCE")
    .setClaims(ImmutableList.of(new Claim("auth_time", true)))
    .build()

Per ulteriori informazioni, consulta l'articolo Autenticare gli utenti con Accedi con Google.

auth_time response

Quando la rivendicazione auth_time è inclusa nella richiesta, viene visualizzata nella risposta del payload del token ID insieme ad altre rivendicazioni standard come iss (emittente), sub (soggetto), aud (pubblico) e exp (ora di scadenza). Il valore dell'attestazione auth_time è un numero JSON che rappresenta il numero di secondi trascorsi dall'epoca di Unix (1° gennaio 1970, 00:00:00 UTC) fino all'ultima autenticazione dell'utente. Questo è un esempio di ID token decodificato che include l'attestazione auth_time:

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "[e-mail]",
  "email_verified": true,
  "nonce": "123-456-7890",
  "auth_time": 1748875426,
  "nbf": 1748880889,
  "name": "Elisa Beckett",
  "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1748881189,
  "exp": 1748884789,
  "jti": "8b5d7ce345787d5dbf14ce6e08a8f88ee8c9b5b1"
}

Il token ID contiene anche un'attestazione iat (emesso alle), che indica l'ora in cui è stato emesso il JWT. Confrontando le rivendicazioni iat e auth_time, puoi determinare il tempo trascorso dall'ultima autenticazione dell'utente rispetto al momento in cui è stato creato il token ID specifico. Ad esempio, se iat è 1748881189 e auth_time è 1748875426, la differenza è di 5763 secondi, ovvero 1 ora, 36 minuti e 3 secondi di tempo trascorso.

Avviso: quando implementi il sistema di gestione degli account, non devi utilizzare il campo email nel token ID come identificatore univoco di un utente. Utilizza sempre il campo sub, in quanto è univoco per un Account Google anche se l'utente modifica il proprio indirizzo email.