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.

Sessioni

Una richiesta di autenticazione da parte di un'applicazione restituisce un token ID. Ad esempio, quando viene premuto un pulsante Accedi con Google, viene restituito un token ID all'applicazione client o server Android, iOS o web che visualizza il pulsante.

L'autenticazione per accedere a un Account Google è un evento distinto e separato. Le rivendicazioni restituite nel token ID rappresentano questo evento. Ad esempio, l'ora e i metodi di autenticazione utilizzati per accedere all'Account Google.

Esistono due momenti di autenticazione e due sessioni utente:

  • Utente <-> Sessione Google Stabilita quando un utente accede al proprio Account Google. Google gestisce il ciclo di vita e la sicurezza di questa sessione. Le attestazioni auth_time e amr forniscono informazioni su questa sessione.
  • Utente <-> Sessione dell'applicazione stabilita dopo l'accesso dell'utente alla tua applicazione, spesso avviato utilizzando Accedi con Google. La tua applicazione gestisce questa sessione utilizzando le rivendicazioni per migliorare le decisioni di gestione della sessione e dell'account.

Spesso gli utenti interagiscono con i servizi Google su più dispositivi, ad esempio smartphone, computer, smart display o TV. L'accesso su ogni piattaforma o dispositivo stabilisce una sessione distinta. Per gli accessi web, viene stabilita una sessione tra il browser specifico e Google. Tieni presente che le modalità di navigazione privata e in incognito creano sessioni separate e isolate. Per questo motivo, un singolo Account Google può avere più sessioni distinte attive contemporaneamente su vari browser e dispositivi. Per maggiori dettagli, consulta Visualizzare i dispositivi con accesso all'account.

Stato dell'Account Google

Gli eventi tipici del ciclo di vita di un Account Google sono:

Le funzionalità del pacchetto di sicurezza descritte in questa guida si applicano agli account attivi o disattivati, ma non agli eventi di creazione o eliminazione dell'Account Google.

Google può disattivare un account in qualsiasi momento. Per alcuni motivi, consulta la sezione Il tuo account è disattivato. Quando ciò si verifica, tutte le sessioni Google attive vengono terminate e il servizio Protezione su più account di Google invia un evento RISC. Gli account disabilitati non possono utilizzare Accedi con Google, il che significa che non viene mai emesso un token ID e quindi non può essere utilizzato per monitorare gli account utente disabilitati.

Sebbene la ricezione degli eventi Protezione su più account (RISC) sia facoltativa, questi eventi fungono da indicatori importanti per gestire la sessione tra l'utente e la tua app e se. Le istruzioni su come implementare RISC e rispondere agli eventi sono descritte in Proteggere gli account utente con Protezione su più account.

Configurazione

Per ricevere ulteriori rivendicazioni, la tua app deve essere pubblicata, verificata e le funzionalità del bundle di sicurezza devono essere attivate. Inizia verificando 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 Pubblico e verifica che lo stato di pubblicazione sia In produzione.
  4. Fai clic su Centro verifica e controlla che lo stato della verifica sia Verificato.

Successivamente, attiva le rivendicazioni aggiuntive:

  1. Fai clic su Impostazioni nel menu.
  2. Nella sezione Impostazioni avanzate, seleziona:
    • Attestazioni durata della sessione per attivare auth_time
    • Attestazioni efficacia dell'autenticazione per attivare amr

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

Funzionalità supportate

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

Riferimenti ai metodi di autenticazione

Authentication Methods References (amr) è un claim OpenID Connect che descrive i metodi utilizzati durante l'ultimo evento di autenticazione tra l'utente e Google.

Tra i possibili valori IANA.AMR, Google supporta i seguenti valori che indicano che:

  • hwk è stato utilizzato un token di sicurezza fisico
  • mfa L'autenticazione a più fattori è stata completata
  • pwd è stata utilizzata una password
  • È stata utilizzata una chiave software come una passkeyswk
  • sms è stato utilizzato un messaggio SMS per la verifica
  • tel è stata utilizzata una chiamata per la verifica

Uno o più di questi valori vengono restituiti come array JSON di stringhe all'interno dell'attestazione amr del token ID.

L'attestazione amr è inclusa nel token ID solo quando sono disponibili informazioni sul metodo di autenticazione utilizzato e potrebbe non essere presente anche se richiesta.

I proprietari di Account Google possono scegliere di richiedere la V2P e quali metodi MFA utilizzare. Quando la protezione avanzata è attivata su un Account Google, è richiesto un metodo V2P efficace come i token di sicurezza Titan (hwk) o le passkey (swk). In entrambi i casi, il valore mfa è presente quando viene utilizzato più di un fattore durante l'accesso all'Account Google.

La presenza di mfa conferma che l'evento di autenticazione soddisfa i requisiti di Google per l'autenticazione a più fattori. Ad esempio, un'autenticazione dell'Account Google con una password (pwd) e una passkey (swk) genera questa rivendicazione "amr": ["mfa", "pwd", "swk"].

Queste risorse forniscono ulteriori informazioni sulla sicurezza dell'account e sull'autenticazione utente: Ottieni la massima sicurezza dell'account con il programma di protezione avanzata, Accedere con una passkey anziché con una password e Utilizzare un token di sicurezza per la verifica in due passaggi.

Gli amministratori di Workspace controllano i criteri di autenticazione per gli account Workspace gestiti e potrebbero richiedere l'autenticazione a più fattori o l'utilizzo di chiavi di sicurezza. Per saperne di più, consulta Panoramica della gestione delle identità Google e Requisito di autenticazione a più fattori per Google Cloud Protezioni e controlli di accesso.

Ora di autenticazione

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 web JSON (JWT) 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. Ciò può essere particolarmente importante per motivi di sicurezza, ad esempio:

  • Prendere una decisione informata in merito alla necessità che la tua app emetta una richiesta di autenticazione aggiuntiva prima di eseguire azioni sensibili dell'utente 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 gestisce 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 delle impronte 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 rischio maggiore.

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.

Richieste

Il metodo specifico utilizzato per richiedere le rivendicazioni auth_time e amr varia a seconda dell'API utilizzata, ma ogni API include un parametro claims facoltativo per richiedere auth_time e amr.

Protocollo OIDC

Quando utilizzi direttamente la piattaforma OAuth, richiedi auth_time aggiungendolo al parametro di richiesta facoltativo claims. Imposta il valore del campo id_token dell'oggetto JSON delle rivendicazioni su {"auth_time":{"essential":true}}. Allo stesso modo, aggiungi {"amr":{"essential":true}} a claims per richiedere amr:

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 },
            "amr": {"essential":true}
          }
        }

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 e amr 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, amr",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

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

GIS per Android

Un metodo setClaims e un oggetto Claim vengono utilizzati per richiedere auth_time e amr.

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 oggetti Claim di tipo auth_time e amr utilizzando setClaims per aggiungerli all'elenco delle 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),
           new Claim("amr", true)
    ))
    .build()

Per saperne di più, consulta Autenticare gli utenti con Accedi con Google.

iOS

L'SDK Accedi con Google per iOS aggiunge un oggetto authTimeClaim e un parametro claims alla classe GIDSignIn, che viene utilizzata per richiedere facoltativamente auth_time e amr.

Le app che utilizzano ASWebAuthenticationSession aggiornano un cookie condiviso a livello di dispositivo. GIDSignIn utilizza questo metodo per impostazione predefinita in iOS 12 o versioni successive e macOS 10.15 o versioni successive. In questo scenario, un utente che accede al proprio Account Google viene autenticato e la sessione viene memorizzata nel contenitore dei cookie condiviso. Qui auth_time è l'ultima autenticazione Google dell'utente sul dispositivo, non solo all'interno della tua app.

SFSafariViewController, WKWebView e UIWebView operano in sandbox isolate all'interno dell'app, quindi evita di utilizzarli quando usi auth_time. Qui auth_time è l'ultimo accesso dell'utente all'app stessa, poiché il valore è sempre recente, è meno significativo.

Per richiedere auth_time, aggiorna le dipendenze GoogleSignIn all'ultima versione e crea un oggetto authTimeClaim, aggiungendolo al set claims.

Per richiedere amr, crea un oggetto amrClaim e aggiungilo al set claims.

Swift

Aggiungi il set di rivendicazioni al metodo GIDSignIn.sharedInstance.signIn: 

let authTimeClaim = GIDClaim.authTime()
let amrClaim = GIDClaim.amr()
let claims = Set([authTimeClaim, amrClaim])



// Start the sign-in process
GIDSignIn.sharedInstance.signIn(
  withPresenting: rootViewController,
  claims: claims
) { signInResult, error in
  guard let result = signInResult else {
    print("Error signing in: (error?.localizedDescription ?? "No error description")")
    return
  }
  // If sign in succeeded, display the app's main content View
  print("ID Token: (result.user.idToken?.tokenString ?? "No token")")
}

Objective-C

Aggiungi il set di rivendicazioni al metodo signInWithPresentingViewController: 

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
GIDClaim *AMRClaim = [GIDClaim AMRClaim];
NSSet *claims = [NSSet setWithArray:@[authTimeClaim, AMRClaim]];



// Include the claims set and start the sign-in process
[GIDSignIn.sharedInstance
  signInWithPresentingViewController:self
                                hint:nil
                              claims:claims
                          completion:^(GIDSignInResult * _Nullable signInResult,
                                      NSError * _Nullable error) {
                            // On success signInResult.user.idToken
                            // contains the requested claims.
                          }];

Per ulteriori informazioni, consulta l'articolo Integrazione di Accedi con Google nell'app per iOS o macOS.

Risposte

Quando le rivendicazioni auth_time o amr sono incluse nella richiesta, vengono restituite nella risposta del payload del token ID insieme ad altre rivendicazioni standard come iss (emittente), sub (soggetto), aud (destinatario) e exp (ora di scadenza).

Le rivendicazioni mancanti sono probabilmente dovute al fatto che l'app non è verificata o che le impostazioni aggiuntive sono disattivate, ovvero l'impostazione predefinita. Segui le istruzioni riportate in Configurazione per verificare che l'ID client e l'app in uso siano verificati e che le rivendicazioni aggiuntive siano attive.

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.

Il valore dell'attestazione amr è un array JSON di stringhe che rappresentano i metodi di autenticazione utilizzati durante l'ultimo evento di accesso all'Account Google.

Questo è un esempio di token ID decodificato che include le rivendicazioni auth_time e amr:

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "alice@example.com",
  "email_verified": true,
  "nonce": "123-456-7890",
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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 ore), che indica l'ora in cui è stato emesso il JWT. Confrontando le attestazioni 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.