Conversational Actions were deprecated on June 13, 2023. For more information, see Conversational Actions sunset.

OAuth and Google Sign-In concept guide (Dialogflow)

The OAuth and Google Sign-In linking type adds Google Sign-In on top of OAuth-based account linking. If you use this linking type in your Action, the flow begins with Google Sign-In, which allows you to check if the user’s Google profile information exists in your system. If it doesn’t, a standard OAuth flow begins. By providing a combination of these two linking types, your users can link their identity in your Action with either a Google or non-Google account. If they choose, they can also create a new account with their Google profile information.

OAuth and Google Sign-in is the recommended account linking solution if any of the following applies:

You have an Action that spans multiple platforms (for example, if your Action works with an Android app).
You have an existing authentication system and you want to allow users to link their identities with non-Google accounts. For example, if you offer a loyalty program and want to make sure that the user doesn’t lose the points accrued on their existing account.

To verify that OAuth and Google Sign-In is the right solution for you, see the Choose your account linking type page.

Key terms

Before you read about how OAuth and Google Sign-in 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"
}

Account sign-in helper intent: A helper intent that you call to request an account linking flow from the Assistant. For more information, see Account Sign-in.
- Context string: A customized string that you add to the account sign-in helper intent that tells the user why you want to link their account.
Authorization code flow: An OAuth 2.0 flow that you can implement with OAuth + Google Sign-In. This flow requires two endpoints:
- Authorization endpoint: The endpoint that presents the sign-in UI to your users that aren’t already signed in. It records consent to the requested access in the form of a short-lived authorization code.
- Token exchange endpoint: This endpoint is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.
Implicit code flow: An OAuth 2.0 flow that you can implement with OAuth + Google Sign-In. This flow requires only an authorization endpoint. During this flow, Google opens your authorization endpoint in the user’s browser. If sign-in is successful, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.
Access token: A token that authorizes your service to access parts of a user’s data. Access tokens are associated with each individual user.
Refresh token: A token that is exchanged for a new access token once a short-lived access token has expired.

Prerequisites

To use the OAuth and Google Sign-In linking type, you need the following:

An OAuth 2 server
A token exchange endpoint

The token exchange endpoint must be extended to add support for Google’s protocols for automatic linking and account creation from an ID token (i.e., add the intent=get and intent=create parameters in requests to this endpoint).

How it works

This section describes the general flow for OAuth and Google Sign-In. The following section, OAuth and GSI flows, describes the various flows that can occur based on a) whether you enable or disable account creation via voice and b) whether you use the implicit or authorization code flow.

The fundamental flow is as follows:

Your Action asks the user for consent to access their Google profile.
After the user gives consent, your Action receives a Google ID token that contains the user’s Google profile information.
You must validate and decode the token to read the profile content.
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, and the Assistant links the user’s identity with their Google account. The user can continue the conversation with the Assistant with their account linked.
2. If it doesn’t, see step 5.
The user can either a) create a new account with their Google profile information or b) sign into your system with a different account. The choices the user is presented with differ based on whether you enable or disable account creation via voice. If the user chooses to sign into your system with a different account, the standard OAuth flow begins.
After the user creates a new account or signs in with a different provider, your service returns an access token to Google. (If you are using the authorization code flow, your service also returns a refresh token.)
The user can now continue the conversation with the Assistant with their account linked.

OAuth and GSI flows

This section goes over the various flows that can occur with OAuth and GSI. These diagrams go over the flows that occur with the authorization code flow rather than the implicit code flow, and assume you are using Dialogflow as the natural language understanding solution for your Action.

Each flow contains these common steps after the user invokes your Action:

In the flow above, you call the actions.intent.SIGN_IN helper intent with a context string you customize. This intent asks the user for permission to access their Google profile information. After the user consents, the Assistant sends a request that contains the profile information for user@gmail.com.

The flows after this point differ based on whether or not you configure account linking with voice and whether the user’s information already exists in your system. Each of these flows is described in the following sections.

Flows with voice account creation enabled

This section details the account linking flows that can occur if you enable account creation via voice.

Flow 1: User’s information exists in your system

In this case, the user represented by user@gmail.com exists in your backend, so your token exchange endpoint returns a token for the user. The user’s identity in your Action is now linked to their Google account. The user’s original request (“Order my usual”) matches the custom intent order_drink. Your webhook then handles the fulfillment of the matched intent and queries your database for user@gmail.com’s usual order. The user can then continue their conversation with the Assistant.

Flow 2: User’s information does not exist and user creates account

Because you enabled account creation via voice and user@gmail.com does not exist in your backend, the Assistant asks the user whether they want to do either of the following:

a) Create a new account on your system using their Google profile information, which is accomplished via voice

b) Sign into your system with a different account

In this case, the user chooses to create a new account via voice. Google calls your service’s token exchange endpoint with a request to create an account. This request contains the Google ID token, which includes the components needed to create a new account. You can then use the information from this token (the user’s name and email address) to create an account for the user.

After the account is created, your service returns an access token and refresh token for the newly created account. The user’s identity in your Action is now linked to their Google account. The user’s original request (“Order my usual”) matches the custom intent order_drink. Your webhook then handles the fulfillment of the matched intent and queries your database for user@gmail.com’s usual order, which does not yet exist because the user is new. Your Action can then ask the user what they’d like to order.

Flow 3: User’s information does not exist and user signs in with different account

You enabled account creation via voice, so the Assistant asks the user whether they want to do either of the following:

a) Create a new account on your system using their Google profile information, which is accomplished via voice

b) Sign into your system with a different account

In this case, the user chooses to sign in with a different account, which starts the standard OAuth flow. If the flow began on a voice-only device, Google transfers the execution to a phone. Google then opens your authorization endpoint in the user’s browser, and, depending on your configuration, the user can choose whether to a) sign in to your service with an existing account that doesn’t use Google Sign In or b) create a new account using a different provider. For more information about the OAuth flow, see the OAuth concept guide.

After verifying the user’s credentials, your service returns an access token and a refresh token to Google. The user’s identity in your Action is now linked to a non-Google account. The user’s original request (“Order my usual”) matches the custom intent order_drink. Your webhook then handles the fulfillment of the matched intent and queries your database for user@gmail.com’s usual order, which does not yet exist because the user is new. Your Action can then ask the user what they’d like to order or ask them to set up their usual order.

Flow with voice account creation disabled

This section details the account linking flow that can occur if you disable account creation via voice.

Flow 4: User’s information does not exist

You did not enable account creation via voice and the user doesn’t exist in your backend, so the standard OAuth flow begins. The Assistant opens your authorization endpoint in the user’s browser (if the flow began on a voice-only device, Google transfers the execution to a device with a screen). The user can choose to either a) sign in with a different provider, if they’ve registered to your service with a different account or b) create a new account with a different provider. For more information on the OAuth flow, see the OAuth concept guide.