Setup an Authorization Server—less for your Actions on Google Application

You Shall Not Pass Until You Link Your Account!

In this blog post, we are going to tackle one of the advanced topics when it comes to building Actions for the Google Assistant: Account linking.

“Account linking is a great way to lets users connect their Google accounts to existing accounts on your service.”

Whenever you want to offer a rich experience for your users: personalised results, shopping cart experience, or access their loyalty card information; your users will need to link their account to your Action. If you’re building a conversational application for your business, you certainly want to be able to authenticate your users.

In order to do that, most of the time, you will probably want to setup your own Authorization Server—ideally on premise—using any popular stack, such as keycloak. But, in this post, I want to show you an easy way to have a fully working Authorization Server, with Scope and Users management, different Grant types, LDAP integration…etc, and most importantly, with zero hassle, thanks to Auth0.

We are not going to define what an Authorization server is, nor how the explicit workflow works. You can get a great and detailed explanation on this post by Ratros Y.

Configuring your Auth0 project

Without further ado, let me walk you through all the necessary steps to get your server up and running.

1/ Create a Machine to Machine aplication:

Next, choose the default Auth0 Management API. And, for the sack of this article, we are going the enable ALL scopes.

CAUTION: For a real world applications, I would recommend that you enable only the necessary scopes!

2/ Your application is now ready. Let’s configure it:

3/ Write down your Auth0 domain, we will need it later on.

4/ In the Allowed Callback URLs configuration, we are going to provide the following urls:

  • The OAuth User Info URL: https://<your-auth0-domain>/userinfo
  • https://oauth-redirect.googleusercontent.com/r/<action-project-id>

In the Allowed Web Origins section, we’ll provide the following origin:

  • https://oauth-redirect.googleusercontent.com

5/ Next, inside the Advanced Settings, we’ll enable the Authorization Code and Refresh Token grant types. These two grant types are required by the Authorization Explicit Flow (aka. Authorization Code Flow).

6/ Next, we’ll use the simple Useraname-Password Database connection in order to authenticate our users (create one if needed):

For more serious and enterprisy applications, I’d recommend using the Entreprise connection.

7/ Let’s then enable the Google connection in the Social Connections settings. You may want to enable more connections as you wish. This will allow our users to log in using their favorite provider:

8/ In this final step, we will need to create a testing account so we can use it from our Actions on Google project:

Please write down the login and password of this testing account, we will use them later, in the Actions on Google project

Configuring your Actions on Google project

Now, let’s make sure that our action is configured properly with the credentials form our authorization server.

1/ In the Account Linking settings, in your Actions on Google project, set the Account creation to No (second option). By using this option we will be able to redirect the users to our Authorization server and obtain their consent during sign-up:

In the Linking type, choose the OAuth and Authorization code options.

2/ Next, let’s provide the Client information (from our Auth0 project):

Use the Client ID and Client secret issued by Auth0 (see in the application settings, in your Auth0 project):

Next, set both Authorization URL and Token URL to:

  • Authorization URL: https://<your-auth0-domain>/authorize
  • Token URL:https://<your-auth0-domain>/oauth/token

These settings can also be found in your Auth0 project settings.

3/ Lastly, since we are using Account Linking in our Action, we must provide a testing account that will be used by the review team at Google when we will submit our Action for publication. We will provide the testing account we’ve created in step 8, in the Auth0 section from above:

The application’s logic (fulfillment)

In order to try out our application and make sure the authorization process is working properly, we’ve designed a simple dialog using Dialogflow. Here are the intents we’re using:

Get Sign In

This is a special intent that will be triggered by the actions_intent_SIGN_IN special event. This event is dispatched by the Actions on Google.

Make sure to enable the webhook call for this intent.

Default Welcome Intent

This is a default welcome intent that will be triggered when you agent starts:

Make sure to enable the webhook call for this intent.

Next, we’ve added a simple fulfillment implementation to handle both of the previous intents. This sample code was adapted from the official documentation:

Note: This sample code is using the new v2 Dialoflow SDK.

Below, I’ve summarized the two sequences of the account linking process (phase 1) which is where the actual authorization process happens; and the phase 2, which is where the Actions on Google runtime is using the stored token to identify the user:

Once the account linking is done, the user must start again the application to proceed. This time the Actions on Google runtime will automatically identify the user:

Note: I’ve intentionally made these sequence diagrams simpler to understand by focusing on the main entities and removing all the extra interactions!

Congratulations! 🎊 You’ve just setup your first Account Linking and Authorization server for your Action using Auth0, Actions on Google and Dialogflow!

Here is a short video of the whole process:

Actions on Google: Account Linking and Authorization CodeFlow

Please give this article some claps and let me know how much you liked it, on Twitter @manekinekko and make sure to follow me for more content 🎉