Alexa Skill - Account Linking with Google APIs
Developing an Alexa skill using Google services may sound like a contradiction to some, but the truth is Alexa’s custom skills let developers program whatever they like and Google Cloud services are some of the best you could find. Many applications could benefit from using their APIs.
We won’t focus on a single Google APIs service, in this post you will only see how to successfully create a link between an Alexa skill user and its Google account. This will enable your skill to receive an access token and use it to make API calls to a Google service, such as Drive, Sheets, Adwords, Maps, or Google Translate.
OAuth Flow
Both Alexa skills and Google services follow an authentication protocol called OAuth2.
Here you can find an explanatory image of the process flow, but I won’t go into details.
All you need to know is that, at the moment of the first authentication, the Google server will grant 2 tokens: a refresh token and an access token.
The difference between these two is that the access token expires after just an hour, while the first one expires:
- if the user revokes access to the app (here)
- if the token has not been used for six months
- if the user exceeded the maximum amount of live tokens
This is crucial to understand. In the Alexa Account Linking procedure everything is managed by their services, this means you never get to see the refresh token.
What you get is the temporary access token that you can use to make API calls. This provides extra security for the users because it leaves developers with limited access to the user’s data.
Step 1 - Create a Google Cloud Project
In order to expose an application to the public, Google requires a very simple setup of a project that you can do in the Google Cloud Console.
Here click on “Select a project”, “New Project” and simply set the name of your Alexa skill.
Now you need to enable the API services you want to use in this project, from the left menu, “APIs & Services”, then “Enable APIs and Services”.
Keep in mind that not every Google API service is free, many of them usually have a limited amount of free calls. Every call one of the user will make through your skill will be made from your project, so make sure you don’t start spending money.
Now we need to create this project credentials, from “APIs & Services”, select “Credentials”.
We will create an “OAuth client ID” type of credentials.
In order to create it, you will need to set up the OAuth Consent Screen, choose an application name (and logo if you want) that the users will see.
You also need to add here the authorized domains that Alexa will use:
alexa-skill-g-api.firebaseapp.com; amazon.com; amazon.co.jp
This guarantees that the users recognize which services are using their data and only those domains are authorized to ask for the user consent.
From “Application Type”, just choose “Other” and set a name, this will not be public.
You will now see a screen with the Client ID and Client Secret of your application. You will need them later.
Step 2 - Create a login page
This step is not mandatory if you don’t plan to publish your skill, however, if you do, the publication process in the Alexa Store requires, for any authentication system you don’t own, that you own the domain presenting the login page.
This is actually a simple step to make, you can host a simple web page anywhere you want, the simplest place to have it is in an S3 bucket.
Access AWS S3 service and create an empty bucket. This bucket must be accessible by the public, so uncheck the “Block all public access” option while creating it.
Then create a simple HTML file like this one (you can add custom css and style if you want):
Notice the google auth link that the user is redirected to:
https://accounts.google.com/o/oauth2/v2/auth?access_type=offline
The access_type parameter is fundamental, as it tells Google that the token may be refreshed even by an automated action, without the explicit consent of the user, and this is how Alexa will always have a valid access token to send you.
Now change the settings of this file in your S3 bucket, make it accessible by the public and copy its object URL. It should be something like this:
https://bucket-name.s3-eu-west-1.amazonaws.com/index.html
Step 3 - Alexa Account Linking Setup
Visit the Alexa Developer Console, access your skill Build page, in the Account Linking section choose the “Auth Code Grant” authorization grant type and setup the following fields:
- Authorization URI: your S3 object URL
- Access Token URI: https://accounts.google.com/o/oauth2/token
- Client ID: the client ID from the Google Cloud Platform project
- Client Secret: the client secret from the Google Cloud Platform project
- Client Authentication Scheme: HTTP Basic (Recommended)
- Scope: this depends on what Google APIs you would like to use, you can find here every possible scope. You can add more than one
- Domain list: these are the domains that the Authorization URI will fetch content from, so we will add “amazonaws.com”
- Default Access Token Expiration Time: leave blank (defaults to Google expiration time which is one hour)
Step 4 - Access APIs services
Now that the setup is complete, the first time the user logs in to your skill he will be redirected to your login page, the parameters will be forwarded to Google services and a couple of tokens will be granted.
Alexa services will keep the refresh token and utilize it to re-validate the user access token that you will receive in the skill request.
Here is a simple example in Python on how to initialize a Google service and make an API call:
