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

> [!NOTE]
> **Note:** Your user is either a) identified through voice recognition or b) configured on the device. If the user's voice is verified but not recognized, the user is considered a guest.

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](https://developers.google.com/assistant/identity/choose-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](https://en.wikipedia.org/wiki/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.

      > [!NOTE]
      > **Note:** New accounts do not typically have a password set. It is recommended that you add Google Sign In to other platforms to enable users to log in via Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password for signing in on other platforms.

## Google Sign-in flows

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

> [!NOTE]
> **Note:** The following flows assume the user gives consent for your Action to access their Google profile information. If a user doesn't give consent, provide them a way to continue in your Action with an alternate, limited flow. For more information, see [Best practices](https://developers.google.com/assistant/identity/best-practices).

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

![](https://developers.google.com/static/assistant/identity/images/gsi-flow-1.png)

> [!NOTE]
> **Note:** A line from *Webhook* to *User* represents a [simple response](https://developers.google.com/assistant/conversational/prompts-simple) that you create and customize. Lines drawn from *Assistant* to *User* represent prompts that are owned by Assistant and have limited options for customization (requests that require permission are always owned by Assistant). From the user's perspective, both kinds of responses are delivered from Assistant.

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:

![](https://developers.google.com/static/assistant/identity/images/gsi-flow-2.png)

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.