OAuth concept guide (Dialogflow)

The OAuth account linking type supports two industry-standard OAuth 2.0 flows: the implicit and authorization code flows. In the implicit code flow, Google opens your authorization endpoint in the user’s browser. After successful sign-in, you return a long-lived access token to Google. This access token is then included in every request sent from the Assistant to your Action.

OAuth is the recommended account linking solution if the following applies:

  • You have an existing implementation of an OAuth 2.0 server, and you cannot extend your token exchange endpoint 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).

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

Key terms

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

  • 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 need them to link their account.

  • Authorization code flow: During this OAuth 2.0 flow, Google opens your authorization endpoint in the user's browser. If sign-in is successful, your service creates an authorization code and returns it to Google. Google sends this authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an access token and refresh token.

    This flow requires two endpoints:

    • Authorization endpoint: The endpoint that is responsible for finding or obtaining consent from users for data access. This endpoint does the following:
      1. Presents the sign-in UI to your users that aren’t already signed in.
      2. Records consent to the requested access in the form of a short-lived authorization code.
    • Token exchange endpoint: This endpoint is used to obtain encrypted strings called tokens that authorize the Action user to access your service. 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: During this OAuth 2.0 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 then included in every request sent from the Assistant to your Action. This flow requires only an authorization endpoint.

  • Access token: A token that authorizes your service to access parts of a user’s data. Access tokens are associated with each individual user and should be unguessable.

  • Refresh token: A token that is exchanged for a new access token once a short-lived access token has expired.

How it works

This section describes the general flow for the OAuth authorization code and implicit flows. The following section, OAuth flows, describes the various flows that can occur with OAuth.

The authorization code flow can be summarized as follows:

  1. Your Action asks the user if they want to link their account with your service.
  2. After the user agrees to link accounts, Google opens your authorization endpoint in the user’s browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.
  3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven’t already granted permission).
  4. Your service creates an authorization code and returns it to Google by redirecting the user's browser back to Google with the authorization code attached to the request.
  5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an access token and a refresh token. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.
  6. After the user has completed the account linking flow, every subsequent request sent from the Assistant to your fulfillment webhook contains an access token.

The implicit code flow can be summarized as follows:

  1. Your Action asks the user if they want to link their account with your service.
  2. After the user agrees to link accounts, Google opens your authorization endpoint in the user’s browser.
  3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven’t already granted permission).
  4. Your service creates an access token and returns it to Google by redirecting the user’s browser back to Google with the access token attached to the request.
  5. After the user has completed the account linking flow, Google calls your service’s APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

The fundamental authorization code flow is as follows:

  1. Your Action asks the user if they want to link their account with your service.
  2. After the user agrees to link accounts, Google opens your authorization endpoint in the user’s browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.
  3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven’t already granted permission).
  4. Your service creates an authorization code and returns it to Google by redirecting the user's browser back to Google with the short-lived authorization code attached to the request.
  5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an access token and a refresh token. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.
  6. After the user has completed the account linking flow, every subsequent request sent from the Assistant to your fulfillment webhook contains an access token.

OAuth flows

This section goes over the various flows that can occur with OAuth.

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 to start the account linking flow. The Assistant asks the user if they want to link their account with your service and shows them a screen with the requested permissions. When the user consents, Google then redirects the user to your service’s authorization endpoint in the browser. The user signs in (or, depending on your configuration, creates a new account) and grants your Action permission to access their data.

The flows after this point differ based on whether or not you implemented the implicit flow or authorization code flow. These flows are described in the following sections.

Flow 1: User signs in with implicit flow

After the user logs in and their credentials are verified, your service creates a long-lived access token and returns it to Google. At this point, the user’s identity in your Action is linked to the account they signed in with, and the access token is attached to each API call Google makes to your service’s APIs.

Flow 2: User signs in with authorization code flow

After the user logs in and their credentials are verified, your service creates an authorization code and returns it to Google.

This authorization code is sent to your token exchange endpoint, which returns both an access token and a refresh token. At this point, the user’s identity in your Action is linked to whatever account they signed in with, and every subsequent request sent from the Assistant to your fulfillment contains an access token.