Google Sign-In for the Assistant

Google Sign In for the Assistant provides the simplest and easiest user experience for account linking and account creation. 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 profile information can be used to create a personalized user experience in your Action. If you have apps on other platforms and they use Google Sign-In, you can also find and link to an existing user's account, create a new account and establish a direct channel of communication to the user.

Authentication Flows

You can use Google Sign-In for the Assistant to implement three different authentication flows.

Google Sign-In only

In the Google Sign-In only authentication flow, you ask the user to give consent to access their Google profile. You then use the information in their profile to identify the user.

This flow is recommended if any of the following applies:

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

For more details on how to implement this flow, see the Google Sign-In only guide.

Google Sign-In and OAuth 2.0 based account linking and creation

Using this flow, if you can't find a match for the Assistant user in your authentication system, you can seamlessly create a new account using the information contained in the Google ID token, without redirecting the user to your account creation web page.

This flow is recommended if all of the following applies:

  • You have an existing authentication system;
  • You want to minimize friction in account creation for Assistant users.

For more details on how to implement this flow, see the Google Sign-In and OAuth 2.0 for linking and creation guide.

Google Sign-In and OAuth 2.0 based account linking

In this authentication flow, you ask the user to give consent to access their Google profile. You then use the information in their profile to search for the user in your existing authentication system. If you can't find a match for the user, they are redirected to your account creation web page to create a new account.

This flow is recommended if all of the following applies:

  • You have an existing authentication system;
  • You want to be in full control of the account creation process.

For more details on how to implement this flow, see the Google Sign-In and OAuth 2.0 for linking guide.

Implement the Google Sign-In only flow

Configure the project in the Actions Console

Follow these steps to configure your project for this flow:

  1. Open the Actions Console and select a project.
  2. Navigate to the Account linking section.
  3. In Account creation, select Yes, allow users to sign up for new accounts via voice.
  4. In Linking type, select Google Sign In.
  5. Open Client Information and take note of the value of Client ID issued by Google to your Actions.

Start the authentication flow during the conversation

Use the Account Sign-in helper intent to start the authentication flow.

After the user authorizes your action to access their Google profile, you will receive a Google ID token that contains the user's Google profile information in every subsequent request to your action.

To access the user's profile information, you need first to validate and decode the token:

  1. Use a JWT-decoding library for your language to decode the token and use Google's public keys (available in JWK or PEM format) to verify the token's signature.
  2. Verify that the token's issuer (iss field in the decoded token) is https://accounts.google.com and that the audience (aud field in the decoded token) is the value of Client ID issued by Google to your Actions that is assigned to your project in the Actions on Google console.

The following is an example of a decoded token:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

If you use the Actions on Google client library for Node.js, it takes care of validating and decoding the token for you, giving you access to the profile content, as shown in the following code snippet:

Dialogflow
const app = dialogflow({
  clientId: CLIENT_ID,
})

app.intent('Default Welcome Intent', conv => {
  conv.ask(new SignIn('To get your account details'))
})

// Create a Dialogflow intent with the `actions_intent_SIGN_IN` event
app.intent('Get Signin', (conv, params, signin) => {
  if (signin.status === 'OK') {
    const payload = conv.user.profile.payload
    conv.ask(`I got your account details, ${payload.name}. What do you want to do next?`)
  } else {
    conv.ask(`I won't be able to save your data, but what do you want to do next?`)
  }
})
Actions SDK
const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('actions.intent.MAIN', conv => {
  conv.ask(new SignIn('To get your account details'))
})

app.intent('actions.intent.SIGN_IN', (conv, input, signin) => {
  if (signin.status === 'OK') {
    const payload = conv.user.profile.payload
    conv.ask(`I got your account details, ${payload.name}. What do you want to do next?`)
  } else {
    conv.ask(`I won't be able to save your data, but what do you want to do next?`)
  }
})

Implement the Google Sign-In and OAuth 2.0 based account linking and creation flow

Configure the project in the Actions Console

Follow these steps to configure your project for this flow:

  1. Open the Actions Console and select a project.
  2. Navigate to the Account linking section.
  3. In Account creation, select Yes, allow users to sign up for new accounts via voice.
  4. In Linking type, select OAuth & Google Sign In and the grant type implemented by your OAuth 2.0 server.
  5. Open Client Information and take note of the value of Client ID issued by Google to your Actions.

Add support for the automatic sign-up flow to your OAuth 2.0 server

Follow these instructions to implement support for the automatic sign-up flow in your OAuth 2.0 server.

Start the authentication flow during the conversation

Use the Account Sign-in helper intent to start the authentication flow.

When you use this flow, if you return a user_not_found error during the automatic sign-up flow, the Assistant will proceed with the rest of the flow and call your token exchange endpoint to create a new account from the Google ID token.

Implement the Google Sign-In and OAuth 2.0 based account linking flow

Configure the project in the Actions on Google console

Follow these steps to configure your project for this flow:

  1. Open the Actions Console and select a project.
  2. Navigate to the Account linking section.
  3. In Account creation, select No, I only want to allow account creation on my website.
  4. In Linking type, select OAuth & Google Sign In and the grant type implemented by your OAuth 2.0 server..
  5. Open Client Information and take note of the value of Client ID issued by Google to your Actions.

Add support for the automatic sign-up flow to your OAuth 2.0 server

Follow these instructions to implement support for the automatic sign-up flow in your OAuth 2.0 server.

Start the authentication flow during the conversation

Use the Account Sign-in helper intent to start the authentication flow.

When you use this flow, if you return a user_not_found error during the automatic sign-up flow, the Assistant will direct the user to your Authorization URL to create a new user.