Alexa Skills are increasingly trying to provide more personalized user experience by offering information about your children's school hours, your electricity bill, etc. In order to achieve this, it is necessary to identify yourself in the Skill with a user and password through an external platform. To do so, Alexa offers Account Linking, which allows us to identify ourselves on our platform with Alexa using the OAuth2 authentication protocol.
This authentication flow is simple on the user´s side, but can be complex for the developer. This is why we have thought it would be interesting to explain how to set up, following some simple steps, an authentication server and configure the Account Linking to be able to login in our platform when activating the Skill.
To exemplify and create the authentication server, we will use Amazon Cognito as it is an easy to set up service that everyone can try as we will not exceed the limits of its free offering.
Step by Step
First we access the Cognito service and select the Manage User Pools option:
Then, we select "Create a User Pool" option and we will get a screen like this:
Notice that we will not go into detail about the configuration of the authentication service as each developer will have a different need. Here is a basic configuration.
The Policies section is set by default.
MFA and verifications, do not forget you need to create the role.
We left by default all remaining sections until we reach the App Clients option and select Add an App Client.
At this step it is important to select the "Generate Client Secret" option. When doing so, we add a name and create our first App Client.
Now, before reviewing the configuration, we are ready to create our user pool.
Once the user pool is created, we will get a menu with new options:
When selecting "App Integration" you will see it refers to the client created in the previous steps.
Next step is to assign a domain name:
Now, we'll make a parenthesis and go to our Alexa skill, specifically to the Account Linking section, and the first thing we'll do is to enable it. Depending on your Skill, you will have to activate or not the rest of the options.
And now, it is time to set the Account Linking. This step is really easy and what we have to do is to select the Auth Code Grant option where we will see the fields we must fill in with the information of our newly created authentication service.
Next, we go to our Amazon Cognito service and copy the url of the created domain:
In this case, our url is: https://alexa-test.auth.eu-west-1.amazoncognito.com with which we can fill in the first two fields:
1. Authorization URI (Uniform Resource Identifier):
As you can see, we added the oauth2/authorize path and the following url parameters:
- redirect_uri= (they appear at the bottom of the Account Linking view).
2. Access Token URI: https://alexa-test.auth.eu-west-1.amazoncognito.com/oauth2/token
Client ID and Client Secret
To obtain these values we go back to our Amazon Cognito service, specifically to the App Client menu.
We can leave the remaining parameters by default.
Once we are ready with this step we can try the authentication with Account Linking. With the Alexa account linked we will obtain the user's access token but we will not be able to access any of our API resources if it uses our user pool as authorizer.
Amazon Cognito expects the token ID rather than the access_token so if we try to access our API with the access token we will obtain an "Unathorized". This happens because Amazon Cognito uses the OpenID authentication protocol while Alexa uses the OAuth2 authentication protocol. This can be easily fixed by going to the App Client settings menu.
The configuration must be similar to the one shown. Please, notice that we checked the Authorization Code Grant and OpenID scope.
Also we've added all the redirect urls (we can get them from the Alexa Account Linking menu) and the logout url, that we'll build in a similar way to the previous ones:
We save the changes and we can now log in to our Skill. Now in each invocation of the skill we will have an Access Token. In the Access Token we won't have all of the user's information, we'll just have the username, unlike the token_id where we had all of the information. To get the user's information (in case we need it for our Skill) we can get it through a link like this:
This call can be done by sending the Access Token to the header.
And now we are ready to go! We have been able to list the main steps to configure the Alexa Account Linking authentication server through Amazon Cognito.
Following these instructions you will be ready to activate your Alexa Skill and log in.
On the next article, we will show you how to use your own front-end to log in instead of the one provided by Amazon Cognito. Stay tunned for our next Alexa blogpost!
We invite you to learn more about virtual voice assistants by reading our other blogpost: