Account linking

Figure 1: With Account Linking, a food ordering Action can welcome existing users back by name and access preferences set on mobile or web apps.

You can use account linking to connect your users' Google accounts with user accounts in your authentication system. This allows you to build richer experiences for your users; for example, you can save the user's food or music preferences, history of transactions, and other information that you can use to provide a more personalized experience.

If your Action is a companion of existing apps on different platforms (for example, the web or Android), you can use account linking to securely make users' preferences available to all platforms, which ensures a consistent cross-platform experience.

Account linking for Actions on Google uses Google Sign-In, Google's secure authentication system, and optionally, OAuth 2.0, the industry-standard protocol for authorization.

Understand the account linking Flow

When the Assistant matches a Google account to a user, you can use account linking to ask for the user's permission to access that Google account. You can use the account data to do the following:

  • To find a match for the account in your authentication system if the user has already used your Action or one of your apps on other platforms.
  • To create a new account in your authentication system for a new user.

Actions on Google offers three different account linking types.

Google Sign-In

Figure 2: The Google Sign-In only account linking type is the recommended solution for Actions that target only the Assistant.

With Google Sign-In for the Assistant, your Action can request access to your user's Google profile during a conversation, including the user's name, email address, and profile picture. The user can complete the whole flow over voice, which provides a frictionless sign-in experience.

This type of account linking is recommended if any of the following applies:

  • You don't have an existing authentication system.
  • You have an existing authentication system and only want to link to users who signed up to your existing apps using their @gmail.com address.

To learn more, see the Google Sign-In developer guide.

OAuth and Google Sign-In

Figure 3: The Google Sign-In with OAuth 2 account linking type is the recommended solution for multi-platform Actions.

The OAuth and Google Sign-In linking type adds Google Sign-In on top of OAuth based account linking. This provides seamless voice-based linking for Google users while also enabling account linking for users who registered to your service with a non-Google identity.

To use this flow, you need to extend one of the supported OAuth 2 standard flows to add support for Google proprietary extensions of the protocol, which allow you to:

  • Seamlessly link accounts using the Google profile information.
  • Seamlessly create new accounts using the Google profile information (optional).

This type of account linking is recommended if you have an existing authentication system and you want to allow users to connect to non @gmail.com addresses.

To learn more, see the OAuth and Google Sign-In developer guide.

OAuth

The OAuth account linking type supports two industry standard OAuth 2.0 flows, the implicit and authorization code flows.

Using this flow is discouraged because it requires transferring the user interaction from voice to screen. You can consider using this flow if you have an existing implementation of an OAuth 2 server, and you cannot extend the token exchange endpoint to add support for Google's protocols for automatic linking and account creation from an ID token.

To learn more, see the OAuth developer guide.