Implementing Account Linking

Implementing account linking with Google takes 3 simple steps.

Step 1. Configure your server

Accounts are linked with industry standard OAuth 2.0 flows. Actions on Google supports the implicit and authorization code flows.

In addition, we highly recommend you implement streamlined identity flows that offer a great experience for your users to sign-in to their existing accounts or even create new accounts. The experience takes two clicks from your users and doesn’t require any username, password, or long configuration steps. To enable the streamlined identity experience on your existing OAuth 2.0 server, see Streamlined Identity Flows.

Step 2: Enable Account Linking

You need to configure the account linking parameters using the Actions on Google console.

  1. Navigate to the Actions console.
  2. Select or create a new project.
  3. Go to the Overview page for the project and click on the Account Linking step.

  4. Follow the step-by-step instructions to set up account linking:

  5. If your app supports seamless account linking:

    1. Select Add quick account linking and fill out fhe fields.

    2. Under Testing Instructions, provide a sample username and password to help us test seamless account linking during the review process for your app then hit save.

Once account linking is set up, you can enable your app to trigger account linking in two ways: when your app is invoked or during a conversation within your app. The following sections describe how to do this.

Account linking at invocation time

To enable account linking at invocation, complete the following steps:

  1. Whitelist the following redirect URI: https://oauth-redirect.googleusercontent.com/r/<google developer project ID>
  2. In your Dialogflow 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:

    Test on a device:

    1. Open the Google app and go to the Discover tab.
    2. Click on the account linking card, which launches the account linking flow. The Google app and the device must be signed into the same account that you use to test the app.

    Testing on the Actions simulator

    1. Invoke your app. Since it's the first time invoking the app with your Google account, the Assistant notifies you that you must link your account.
    2. In the Log area, copy and paste the URL from the debugInfo.sharedDebugInfo.debugInfo field into your web browser. You will be redirected to the authentication URL for your own server that was specified in Dialogflow or in the Actions Console.
    3. Follow the OAuth login flow to completion. The account linking works if you are redirected to google.com with a URL param of result_code=SUCCESS.
    4. In the Actions simulator, invoke your app again. Your app responds to the user and receives an access_token in all HTTP requests to your fulfillment. Use the Node.js client library function DialogflowApp.getUser().access_token to obtain the token.

During the conversation

You can have users sign-in to their accounts that are associated with your service by requesting the actions.intent.SIGN_IN intent during a conversation.

The Request the signin helper section of this doc shows how to request this intent; the Getting the results of the helper section of this doc shows how to check if the user succesfully linked their account after the request.

Request the signin helper

Request this intent if you are unable to find an accessToken in the user object This means that the user has not yet linked their account.

Node.js
function signIn(app) {
  app.askForSignIn();
}
JSON
{
  "conversationToken": "{\"state\":null,\"data\":{}}",
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "initialPrompts": [
          {
            "textToSpeech": "PLACEHOLDER_FOR_SIGN_IN"
          }
        ],
        "noInputPrompts": []
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.SIGN_IN",
          "inputValueData": {}
        }
      ]
    }
  ]
}

Getting the results of the helper

After the user responds to the helper, you receive a request to your fulfillment and can check to see if the user successfully linked their account.

After requesting the actions.intent.SIGN_IN intent, you will receive an argument containing a SignInStatus with a value of either OK, CANCELLED, or ERROR. If the status is OK you should be able to find an accessToken in the user object.

Node.js
function signInHandler(app) {
  if (app.getSignInStatus() === app.SignInStatus.OK) {
    let accessToken = app.getUser().accessToken;
    // access account data with the token
  } else {
    app.tell('You need to sign-in before using the app.');
  }
}
JSON
{
  "isInSandbox'": false,
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      }
    ]
  },
  "inputs": [
    {
      "rawInputs": [
        {
          "query": "i think so",
          "inputType": "VOICE"
        }
      ],
      "arguments": [
        {
          "name": "SIGN_IN",
          'extension': {
            "@type": "type.googleapis.com/google.actions.v2.SignInValue",
            "status": "OK"
          }
        }
      ],
      "intent': "actions.intent.SIGN_IN"
    }
  ],
  "user": {
    "userId": "user123"
  },
  "device": {
    "locale": "en-US"
  },
  "conversation": {
    "conversationId": "1494606917128",
    "type": "ACTIVE",
    "conversationToken": "[\"_actions_on_google_\"]"
  }
};

Step 3: Verify your implementation

If you are only using standard account linking without seamless identity, you can validate your implementation by using the OAuth 2.0 Playground tool. In the tool, do the following steps:

  1. Click the gear icon to open the OAuth 2.0 Configuration window.
  2. In the OAuth Endpoints field, select Custom.
  3. Specify your OAuth 2.0 endpoints and the Google client ID and client secret in the corresponding fields.
  4. In the Step 1 section, don't select any Google scopes; instead, type a scope valid for your server, and click Authorize APIs.
  5. In the Step 2 and Step 3 sections, step through the OAuth 2.0 flow and verify that each step works as intended.

Seamless identity verification

If you are using seamless identity, validate the steps above and then use the gala-demo tool to validate the assertion flows. In the demo tool, complete the following steps:

  1. Click the login button to grant permission to the tool to access your profile information (this is only needed the first time you use the tool).
  2. In the service ID field, provide your Google Cloud Project ID plus a _dev suffix. For example, if your project ID is my_gcp_project, enter my_gcp_project_dev.

  3. Add all scopes needed for testing in the next field and click on Start Demo.

  4. An account chooser screen will be displayed. You can either use your logged account (triggering the seamless identity flows) or click to use another account. In that case your standard OAuth flow will be triggered by presenting the Authorization screen.
  5. At the end of the flow, your access token will be displayed in the UI and will be used in the subsequent calls to your app, on your phone or Actions simulator when testing your app.

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.