Google Sign-In concept guide

Google Sign-In (GSI) for Assistant provides the most seamless linking experience for users and is the easiest flow for developers to implement. With GSI, your Action can request access to your user’s Google profile during a conversation and, if the user consents, receive the user’s name, email address, and profile picture. Your Action can then use this information to check if the user has a Google account in your system. If not, your Action asks the user if they want to create a new account in your system based on their Google profile information.

GSI is the recommended account linking solution if any of the following applies:

  • You don’t have an existing authentication system and/or you expect all your users to have a Google account. For example, if your Action is specifically targeting Assistant, you can expect all your users to have Google accounts.
  • You have an existing authentication system and only want to link users who signed into your system using their Google accounts.

To verify that GSI is the right solution for you, see the Choose your account linking type page.

Key terms

Before you read about how GSI works, familiarize yourself with the following terms:

  • Google ID token: A signed assertion of a user's identity that contains a user's basic Google profile information (their name, email address, and profile picture). A Google ID token is a JSON Web Token (JWT).

    The following is an example of a decoded token:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

  • user.verificationStatus: A property set by the system to indicate if the current session has a verified user.

  • user.accountLinkingStatus: A property set by the system to indicate if the user in the current session has a linked identity.

  • Account linking system scene: A predefined scene that implements the confirmation flow for account linking, and can be customized to fit specific use cases.

How it works

The fundamental flow for GSI is as follows:

  1. Your Action asks the user for consent to access their Google profile.
  2. After the user gives consent, your Action receives a Google ID token that contains the user’s Google profile information.
  3. Validate and decode the token to read the profile content. If you use the Actions on Google Fulfillment library for Node.js, it validates and decodes the token for you.

  4. Your Action uses this token to check if the user’s Google profile information exists in your system.

    1. If it does, the user has already signed into your system with their Google account. The user can continue the conversation with Assistant with their identity linked to their Google account.

    2. If it doesn’t, the user can create a new account in your system with the information contained in the Google ID token. The user can then continue the conversation with Assistant with their new account linked.

Google Sign-in flows

This section describes the various flows that can occur with Google Sign-in.

Flow 1: User’s information exists in your system

The following diagram shows the end-to-end flow that occurs with GSI when the user’s information already exists in your system:

In this case, you transition to the account linking system scene and provide a customized rationale. This scene asks the user for permission to access their Google profile information.

After the user consents, Assistant sends a request that contains the profile information for user@gmail.com. In this case, the information contained in the Google ID token for user@gmail.com matches an account in your system, so the user’s identity in your Action is automatically linked to that account. Your webhook can then read the user’s usual order from a database and respond accordingly.

Flow 2: User’s information does not exist in your system

The following diagram shows the end-to-end flow that occurs with GSI when the user’s information does not exist in your system:

In this case, the information contained in the Google ID token for user@gmail.com does not match an account in your system, so Assistant asks the user if they’d like to create a new account. The user can complete the account creation process with voice rather than transferring to a screened device.

When the user agrees to create an account, your service uses the information in the ID token (the user’s name and email address) to create an account for the user. Once the account is created, the user’s identity in your Action is linked to their new Google account.

In this case, the user does not have a usual order because they are new to the service, so your Action asks what they want to order. You can also ask the user if they’d like to set their most recent order as their usual order.