Account Linking

Every Cloud-to-cloud integration must include a mechanism for authenticating users.

Authentication allows you to link your users' Google accounts with user accounts in your authentication system. This allows you to identify your users when your fulfillment receives a smart home intent. Google smart home only supports OAuth with an authorization code flow.

Once you have an OAuth 2.0 implementation, you can optionally configure OAuth-based App Flip, which allows your users to more quickly link their accounts in your authentication system to their Google accounts.

OAuth

For smart home, you must use OAuth with an authorization code flow, which requires you to have two endpoints: the authorization and token exchange endpoints.

When you have authenticated a user, the user's third-party OAuth 2.0 access token is sent in the authorization header when smart home intents are sent to your fulfillment. All users have to perform account linking, because device information is sent to the Google Assistant with the action.devices.SYNC intent, which requires account linking.

Your Cloud-to-cloud integration is expected to support multiple Google users connecting to the same user account (for example, when users give access to other users in their household). If your service can't support multiple user connections, it should provide errors at account linking time.

For instructions on how to set up an OAuth 2.0 server for your integration, see Implement your OAuth 2.0 server.

OAuth-based App Flip

OAuth-based App Flip Linking (App Flip) allows your users to easily and quickly link their accounts in your authentication system to their Google accounts. If your app is installed on your user’s phone when they initiate the account linking process, they are seamlessly flipped to your app to obtain user authorization.

This approach provides a faster and easier linking process since the user does not have to re-enter their username and password to authenticate; instead, App Flip leverages the credentials from the user's account on your app. Once a user has linked their Google account with your app, they can take advantage of any integrations that you have developed.

You can set up App Flip for both iOS and Android apps.

This figure shows the steps for a user to link their Google account to your authentication system. The first screenshot shows how a user can select your app if their Google account is linked to your app. The second screenshot shows the confirmation for linking their Google account with your app. The third screenshot shows a successfully linked user account in the Google app.
Figure 1. Account linking on a user's phone with App Flip.

Requirements

To implement App Flip, you must fulfill the following requirements:

  • You must have an Android or iOS app.
  • You must own, manage and maintain an OAuth 2.0 server which supports the OAuth 2.0 authorization code flow.

For more information on the OAuth linking authorization code flow, see Implement your OAuth 2.0 server.

For instructions on how to configure App Flip for your integration, see OAuth-based App Flip.

Previous
Fulfillment