Pacchetto di sicurezza

Questa guida descrive una raccolta di funzionalità che restituiscono indicatori di attendibilità aggiuntivi su un Account Google. Questi indicatori di attendibilità 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 rivendicazioni aggiuntive, 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 Stato pubblicazione sia In produzione
  5. Fai clic su Centro verifiche nel menu

  6. Verifica che Stato 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 sull'età della sessione per attivare auth_time.

Funzionalità supportate

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

auth_time

La rivendicazione 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. Considerala 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.

La rivendicazione 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 sul 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 step-up aggiuntiva 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.

  • Utilizzare la freschezza e la stabilità della sessione dell'Account Google dell'utente come indicatore di fiducia. In generale, un valore auth_time recente indica la freschezza, mentre un valore precedente indica la 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. Indipendentemente da ciò, 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 si tratta di un'indicazione di un utente attivo e coinvolto e può essere interpretata come un indicatore 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 digitali o del volto e sblocchi 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 poco frequenti all'Account Google e aggiornamenti corrispondenti di auth_time. Pertanto, in questo caso, 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. È previsto che auth_time venga utilizzato insieme ad altri indicatori, ad esempio se l'autenticazione a più fattori (MFA) è attivata, 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 la rivendicazione auth_time varia a seconda dell'API utilizzata, ma ogni API include un parametro claims facoltativo per richiedere auth_time.

Protocollo OIDC

Quando utilizzi direttamente la piattaforma OAuth, richiedi auth_time aggiungendola al parametro di richiesta delle rivendicazioni facoltative. Imposta il valore del id_token campo 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}}}

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 rivendicazioni aggiuntive. 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 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 di 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 aggiungerlo 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 saperne di più, consulta Autenticare gli utenti con Accedi con Google.

iOS

L'SDK Accedi con Google per iOS aggiunge un oggetto authTimeClaime un parametro claims alla classe GIDSignIn utilizzata per richiedere facoltativamente auth_time.

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

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

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

Swift

Aggiungi l'insieme di rivendicazioni al metodo GIDSignIn.sharedInstance.signIn: 

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



// 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 l'insieme di rivendicazioni al metodo signInWithPresentingViewController: 

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
NSSet *claims = [NSSet setWithObject:authTimeClaim];



// 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 saperne di più, consulta Integrare Accedi con Google nella tua app per iOS o macOS per altre informazioni.

Risposta auth_time

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 (oggetto), aud (pubblico) ed exp (ora di scadenza). Il valore della rivendicazione 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. Di seguito è riportato un esempio di token ID decodificato che include la rivendicazione auth_time:

{
  "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,
  "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 una rivendicazione 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.