Account linking with OAuth 2.0

Account Linking lets users connect their Google accounts to existing accounts on your service. Accounts are linked with industry standard OAuth 2.0 flows. Actions on Google supports the implicit and authorization code flows.

See OAuth 2.0 Account Linking Overview for information on what flow is right for your situation.

User Experience

If a user invokes your actions that require signin, the Google Assistant prompts users to link their account. For example, if users are interacting with Google Home, the authorization flow might look like this:

"It looks like your <invocation name> account is not linked yet. You can link <invocation name> to your Google Account from the Google Home app."

At this point, the requesting user receives a card at the top of their Google Home app that provides a link to your consent screen.

Once the user has completed the account linking flow on your web application, they can invoke your action, and your action can then authenticate calls to your services by obtaining calling assistant.getUser().access_token.

Policies

See Actions on Google Policies for specific account linking policies. If users sign in to your service using Google Sign-In, you must comply with the API Terms of Service, including not requesting irrelevant permissions.

Enabling Account Linking

API.AI

  1. Whitelist the following redirect URI: https://oauth-redirect.googleusercontent.com/r/<google developer project ID>
  2. In your API.AI project, click Integrations in the left navigation.
  3. Click on the Actions on Google card (enable the card if it's not already enabled).
  4. Select Sign in Required for the welcome intent and any other intent that requires sign in.

  5. In the expanded OAuth 2.0 form, fill out the fields with your OAuth 2.0 client configuration. When filling in scopes, ensure they are space delimited.

  6. Preview and test the authorization flow.

At runtime, your endpoint receives an OAuth 2.0 access token that you can use to authenticate the user to make API calls to your web server. Use the Node.js client library function ApiAiAssistant.getUser().access_token to obtain the token.

Actions SDK

You define account linking in the accountLinking object in your action package. To set up account linking:

  1. Whitelist the following redirect URI: https://oauth-redirect.googleusercontent.com/r/<google developer project ID>
  2. Add a signInRequired=true flag to the main action and any other action that requires sign in.

{
  "versionLabel": "hello action v0.1",
  "agentInfo": {
    "languageCode": "...",
    "projectId": "...",
    "voiceName": "...",
    "accountLinking": {
      "grantType": "AUTH_CODE_GRANT|IMPLICIT_GRANT",
      "clientId": MY_CLIENT_ID,
      "clientSecret": MY_CLIENT_SECRET,
      "authenticationUrl": AUTH_URL,
      "accessTokenUrl": TOKEN_URL,
      "scopes": [
        "scope1"
      ]
    }
  },
  "actions": [
    {
      "initialTrigger": {
        "intent": "..."
      },
      "httpExecution": {
        "url": "..."
      },
      "signInRequired": true
    }
  ]
}
3. Preview and test the authorization flow.

At runtime, your endpoint receives an OAuth 2.0 access token that you can use to authenticate the user to make API calls to your web server. Use the Node.js client library function ActionsSdkAssistant.getUser().access_token to obtain the token.