Authenticating smart home Actions for the Google Assistant with Auth0

When you’re building a smart home Action for the Google Assistant, one of the setup steps is to add account linking. These Actions require an OAuth 2.0 integration between the Google Assistant and your service in order to verify that each query and command are coming from an authorized user.

Large companies with existing smart home products may already have an OAuth service and engineers who are able to keep it secure. For smaller companies or individual developers, setting up an OAuth service may be additional work in an area where they have little experience. An insecure authentication system isn’t good for developers or users, but there are managed services that provide off-the-shelf solutions for OAuth.

You should take the time to consider which authentication solution makes the most sense for you. Auth0 is one example that provides many different authorization services, such as username/password and identity providers like Google Sign-In.

In this post, I’m going to show how to use Auth0 to facilitate authentication for a smart home Action, allowing you to focus more on the integration and less on the account management.

Create an Actions project

First, you should create the project. This will create a project id, which you will use later in setting up your OAuth.

Open the Actions console and click Add/import project. Type in the name of your project, then click Create Project.

You will be directed to the onboarding page. You should select the Home control card and then Smart home. This step configures your project to be a smart home Action.

Once you’ve entered the console, click on the settings icon next to the Overview option and then select Project settings. You’ll see the project’s name and unique project ID. Take note of the project ID, you’ll use it later to create a callback URL.

Setting up Auth0

Go to the Auth0 website and create an account if you haven’t already.

Once you’ve started with Auth0, you’ll need to create a new tenant. This is like the domain for the project, under which you can have many separate applications that can be authenticated. In the dropdown menu, select Create tenant.

Give your tenant a name, or its Tenant Domain. Take note of this domain, you’ll use it to create your authorization and token URLs.

After creating your tenant, go to the Applications page. This is where you create an application that will authenticate your users.

When you first visit the page, you’ll see that a default application has already been created. We can use this for configuring our authorization. Click on the settings icon to open up the application settings where you’ll start setting up the connection between your Action and OAuth.

At the top of the page is information about the application. Take note of the Client ID and Client Secret. You will use these later.

For Application Type, select Regular Web Application, as the Google Assistant will send OAuth requests to Auth0 on behalf of a given user.

For Allowed Callback URLs, you’ll need two URLs that are separated by commas:

• The first is https://<auth0-tenant-id>.auth0.com/userinfo. This URL will be used to read basic information about the user’s identity. Make sure to replace <auth0-tenant-id> with your actual tenant ID.
• The second is https://oauth-redirect.googleusercontent.com/r/<actions-project-id>. This URL will be called during the account linking process to pass authentication information to the Google Assistant. Make sure to replace <actions-project-id> with your actual project ID.

For Application Login URI, do not provide any value. Auth0 will provide a default login page that you can use.

For Allowed Web Origins, enter https://oauth-redirect.googleusercontent.com. This domain will be allowed to participate in cross-origin authentication.

There are additional settings here such as the application’s name, description, and logo. You can fill these out as needed.

Next, go to the Connections tab for your application. Here you will see all the possible ways that users can authenticate. For now, turn off Username-Password-Authentication and leave Google Sign-In on. You can configure all of the services you want later.

Now that you’ve configured your application, go back to the Actions console to finish setup and create your webhook.

Account Linking

In the Actions console, open the Account linking page under Advanced Options.

Disable automatic account creation, selecting No, I only want to allow account creation on my website. Select OAuth as the linking type and Authorization code as the grant type.

Below, enter the client ID and client secret from your Auth0 application. For the Authorization URL and Token URL, use https://<auth0-tenant-id>.auth0.com/authorize and https://<auth0-tenant-id>.auth0.com/oauth/token respectively. Make sure to replace <auth0-tenant-id> with your actual tenant ID.

Add the openid and email Scopes, which will allow you to get user information in your Action.

Finally, add testing instructions. When submitting your smart home Action for certification, the reviewers will need guidance on authenticating so that they can assure your Action works as expected. For example, if you are using Google Sign-In, instruct the reviewers to use their Google account. If you are using a basic username and password, provide test credentials.

Save these settings. Now that you have configured your authentication, you will need a way to identify the user from your webhook so you can provide the Google Assistant with that user’s devices.

Authentication in your webhook

A user’s smart home devices may already be stored in a database, such as Cloud Firestore. In this format there may be a collection of users, each identified by an email address. Each user document may have a collection of devices.

The smart home intents SYNC, QUERY, and EXECUTE can be easily handled by querying the database, and then responding with the database results.

As part of the OAuth integration, your webhook will receive an access token from Auth0 as a header. To obtain the email address, you will need to send this token back to Auth0 and request user information. Auth0 has a library for Node.js which can simplify the calls to the service from your webhook.

Note: If you’re using Cloud Functions for Firebase, you are unable to make outbound network calls on the free tier. You would need to upgrade to a different plan, such as the pay-as-you-go Blaze tier.

To set up your Auth0 library and the Actions on Google library, you can view the snippet below:

The access token is in a header field called authorization. It will have the access token in the format Bearer 123ABC. To obtain the access token, you can get a substring for this value.

To get the user information, you can create a function to return this information like below:

Now that you have a way to get the email, you can use this function in your smart home intents. The following code connects the user information from the getEmail function to your smart home SYNC intent:

From this example, you can use the same code template to get the user email and query the database for the QUERY and EXECUTE intents.

Once your webhook is complete and deployed, you can go to the Actions page in the Actions console and provide your webhook’s fulfillment URL.

Testing

After everything has been configured, go to the Simulator page in the Actions console and click the Start Testing button. You will see a dialog appear. Click Done and your project will be put into a test state.

Note: Until you start account linking on your phone, you will not be able to use the simulator to send commands.

On your phone, open the Google Home app and go to the smart home accounts list. Make sure you’re logged in with the same Google account on both the Actions console and the mobile app. You will see your test Action appear at the top of the list.

When you click on the Action, you will be redirected to this generic login page. You can see branding elements such as the Auth0 name and logo appear. There are also more advanced ways to personalize the login page in the Auth0 console.

Selecting the Log In With Google button will open a Google sign-in page, which allows you to select the account you want.

After authenticating, your webhook will be called and respond with that user’s smart devices. Users will now be able to query the status and control their devices securely.

Conclusion

Visit the smart home documentation to learn more about how to build your own smart home Action, including additional features like request sync and report state. Beginners to smart home can also try out the codelab and the sample project to get a deeper understanding of the platform.

Want more? Head over to the Actions on Google community to discuss Actions with other developers. Join the Actions on Google developer community program and you could earn a $200 monthly Google Cloud credit and an Assistant t-shirt when you publish your first app.