Security bundle

This guide describes a collection of features that return additional trust signals about a Google Account. These trust signals help your account management system to make risk-based decisions during sign up, account creation, and later for returning users.

Sessions

An authentication request by an application returns an ID Token. For example, when a Sign in with Google button is pressed an ID Token is returned to the Android, iOS, or Web client or server application displaying the button.

Authentication to sign-in to a Google Account is a distinct and separate event. The claims returned in the ID Token represent this event. For example, the authentication time and methods that were used to sign in to the Google Account.

There are two authentication moments and two user sessions:

• User <-> Google SessionEstablished when a user signs into their Google Account. Google manages this session's lifecycle and security. The auth_time and amr claims provide you insights into this session.
• User <-> Your Application SessionEstablished after the user signs in to your application, often initiated using Sign in with Google. Your application manages this session using the claims to improve session and account management decisions.

Users often interact with Google services across multiple devices, such as phones, desktop computers, smart displays, or TVs. Signing in on each platform or device establishes a distinct session. For web sign-ins, a session is established between the specific browser and Google; note that Private Browsing and Incognito modes create their own separate, isolated sessions. Because of this, a single Google Account can have multiple distinct sessions active simultaneously across various browsers and devices. For additional details, refer to See devices with account access .

Google Account status

The typical events of a Google Account lifecycle are:

• a person chooses to Create a Google Account , then
• Google may disable the account or a user may re-activate it after following How to recover your Google Account or Gmail , and
• a person may decide to Delete your Google Account or due to Inactive Google Account Policy Google may delete the account.

The Security Bundle features described by this guide apply to active or disabled accounts, but not to Google Account creation or deletion events.

Google may disable an account at any time, for some of the reasons see Your account is disabled . When this occurs any active Google sessions are terminated and a RISC event is sent by Google's Cross-Account Protection service. Disabled accounts are blocked from using Sign in with Google, meaning an ID token is never issued and so cannot be used to monitor for disabled user accounts.

While receiving Cross-Account Protection (RISC) events is optional, these events serve as important signals to manage the session between the user and your app and whether. Instructions on how to implement RISC and respond to events is described by Protect user accounts with Cross-Account Protection .

Setup

To receive additional claims your app needs to be published, verified , and security bundle features enabled. Start by confirming that your app is published and verified:

1. Open Google Auth Platform
2. Select or Create the Project for your app
3. Click Audienceand confirm Publishing status is In production
4. Click Verification Centerand confirm Verification Status is Verified

Next, enable additional claims:

1. Click Settingsin the menu
2. Under Advanced Settingsselect:
   • Session age claims to enable auth_time
   • Authentication strength claims to enable amr

To learn more, visit the OAuth App Verification Help Center .

Supported features

This section describes the individual features that make up the Security Bundle.

Authentication Methods References

Authentication Methods References ( amr ) is an OpenID Connect claim that describes the methods used during the last authentication event between the user and Google.

From the possible IANA.AMR values Google supports the following values indicating that:

• hwk a hardware security key was used
• mfa Multi-factor Authentication was completed
• pwd a Password was used
• swk a software key such as a Passkey was used
• sms an SMS message was used for verification
• tel a phone call was used for verification

One or more of these values are returned as a JSON array of strings within the ID token amr claim.

The amr claim is included in the ID token only when information is available on the authentication method used, it may not be present even when requested.

Google Account owners may choose to require 2SV and which MFA methods to use. When Advanced Protection is enabled on a Google Account a strong 2SV method such as Titan security keys ( hwk ) or Passkey ( swk ) are required. In both situations, the mfa value is present when more than one factor is used during sign-in to the Google Account.

The presence of mfa confirms the authentication event met Google's requirements for Multi-Factor Authentication. For example, a Google Account authentication with a Password ( pwd ) and a Passkey ( swk ) results in this claim "amr": ["mfa", "pwd", "swk"] .

These resources have more information on account security and user authentication: Get Google's strongest account security with the Advanced Protection Program , Sign in with a passkey instead of a password , and Use a security key for 2-Step Verification .

Workspace admins control authentication policy for managed Workspace accounts, and may require MFA or use of security keys. See Overview of Google identity management and Multi-factor authentication requirement for Google Cloud Login protections & controls for more.

Authentication time

The auth_time claim is a standard part of the OpenID Connect protocol that provides information about when the End-User most recently authenticated with Google. It is a JSON number representing the number of seconds that have elapsed since the Unix epoch (January 1, 1970, 00:00:00 UTC) and is the time the user last authenticated. Think of it as a timestamp indicating the user's last login event to their Google Account from the current device or browser. This claim is included within the ID Token, which is a JSON Web Token (JWT) containing verified information about the authentication and the user.

The auth_time claim is valuable for your application because it lets you determine how recently a user has actively logged into a Google Account on the device or browser they are using. This can be particularly important for security purposes such as:

• Making an informed decision about whether your app should issue an additional step-up authentication challenge prior to performing sensitive user actions like deleting the account, changing account contact methods, or making a payment. Google does not support Google Account reauth requests.

• Using the freshness and stability of the user's Google Account session as a trust signal. Generally speaking, a recent auth_time value is an indication of freshness, while an older value indicates stability.

For web apps, the combination of the user's browser and operating system constitute a session after the user signs into their Google Account. Independently, your website also maintains a separate user session. A newer auth_time value indicates the user recently signed into their Google Account. Often this is an indication of an active, engaged user and can be interpreted as a signal of lower risk.

On mobile platforms such as Android users typically sign-in directly into their device using biometric methods like fingerprint or facial scanning and device specific PIN or pattern unlocks. Mobile apps and platforms often use these platform based authentication methods rather than creating a new session with Google, resulting in infrequent Google Account sign-ins and corresponding updates to auth_time . So here a recent auth_time value may signal a change to a long running Google Account session and thus increased risk.

Trust signals are a nuanced subject. auth_time is expected to be used along with other signals such as whether multi-factor authentication (MFA) is enabled, the authentication method used, and the duration of the user session between your application and your platform.

Requests

The specific method used to request the auth_time and amr claims differs by the API used, however every API includes an optional claims parameter to request auth_time and 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} 
 } 
 } 
 

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

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

 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 
 ")" 
 ) 
 } 
 

 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. 
  
 }]; 
 

Responses

When the auth_time or amr claims are included in the request, they are returned in the ID Token payload response alongside other standard claims like iss (issuer), sub (subject), aud (audience), and exp (expiration time).

Missing claims are likely due to the app not being verified or additional settings are disabled, which is the default. Follow the instructions in Setup to confirm the Client ID and App in use are Verified and additional claims enabled.

The value of the auth_time claim is a JSON number representing the number of seconds that have elapsed since the Unix epoch (January 1, 1970, 00:00:00 UTC) until the time user authentication last occurred.

The value of the amr claim is a JSON array of strings representing the authentication methods used during the last Google Account sign-in event.

This is an example of a decoded ID Token that includes the auth_time and amr claims:

 { 
  
 "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" 
 } 

The ID Token also contains an iat (issued at) claim, which indicates the time the JWT was issued. By comparing the iat and auth_time claims, you can determine the time elapsed since the user's last authentication relative to when the specific ID Token was created. For example, if iat is 1748881189 and auth_time is 1748875426, the difference is 5763 seconds, which represents 1 hour, 36 minutes, and 3 seconds of elapsed time.