Alexa Account Linking using Amazon Cognito User Pool

This article describes how to create Account Linking between developer's account system and Amazon account system. In this case, Amazon Cognito User Pool will be used as the developer's account system. By using it, developer can quickly create Account Linking between their account and Amazon account without writing one line of code.

For more information about Amazon Cognito User Pool, please refer to the developer guide.

What is Account Linking

The following is an explanation from Alexa Docs

You would use account linking if your skill needs personalized data from another system. For example, suppose you own a web-based service "Car Fu" that lets users order taxis. A custom skill that lets users access "Car Fu" by voice would be very useful. For example, "Alexa, ask "Car Fu" to order a taxi." Completing this request requires the skill to access your "Car Fu" service as a specific "Car Fu" user for profile and payment information. Therefore, you need a link between the Amazon account used with the Alexa device and the "Car Fu" account for the user.

Account linking in the Alexa Skills Kit uses OAuth 2.0. The following diagram explains the flow of obtain an AccessToken from your OAuth2.0 system.

Alexa will send all the subsequent directives together with AccessToken. In the Lambda backend, the program should verify and decode the AccessToken to get user related information.

Configure App Client OAuth 2.0 Settings

By default, OAuth 2.0 for App Client in Cognito User Pool is not enabled. Follow the following step to enable Auth2.0.

Go to Cognito User Pool Console
On the left side navigation bar, under App integration, select App client settings
Find the App Client created in Create a Cognito User Pool Client, if you followed the guide, it should be named alexa
Under Enabled Identity Providers，select Cognito User Pool
In Callback URL(s)，enter Redirect URLs copied from Alexa Developer Console. In Alexa Developer Console, choose Account Linking, scroll down to the bottom, you should be able to find three Redirect URL. Alexa redirect to different url based on user's region. To serve all the Alexa users, it is suggested to copy all the URLs.
In Allowed OAuth Flows session，choose Authorization code grant
In Allowed OAuth Scopes session，choose openid
Click Save changes

Configure Cognito User Pool domain name

The default domain name of Cognito follows the pattern https://<domain-prefix>.auth.<region>.amazoncognito.com。 You can use your own domain，to get more information please refer to Adding a Custom Domain to a User Pool。 In this lab, we will use the default domain name.

Go to Cognito User Pool Console
On the left side bar, under App integration, choose Domain name
Enter domain prefix and click Check availability, the domain name must be unique
When promoted the domain is available，choose Save changes

Configure Account Linking in Alexa Developer Console

Go to Alexa Console
In the Skills list，choose the previously created skill
On the left side navigation bar，choose Account Linking
Under Security Provider Information，choose Auth Code Grant
Enter https://<your-cognito-domain>/oauth2/authorize in Authorization URI
Enter https://<your-cognito-domain>/oauth2/token in Access Token URI
Enter Client ID and Client Secret, you can find in them in Cognito User Pool console, under App Clients section
Click Add scope and input openid. For Smart Home skill, at least one scope should be specified
Click Save on the top right corner

For more about Cognito OAuth2.0 URI, please refer to Amazon Cognito User Pools Auth API Reference

Enable Account Linking in Alexa App

Only the Developer Account can see the Skill in development. You must use the same account as creating the skill. You may also need a VPN to use the Alexa APP if you are in China.

Launch Alexa APP on mobile phone
Click the button on the top left corner
Choose Skills & Games
On Skills & Games page，click the DEV in the sliding window.
Your created Smart Home Skill SmartLamp should be listed below. Click it to continue.
Click the Enable To Use button
On the popup window, input your email and password, if have not registered yet, sign up one
Account Link success

So far, the account linking between Alexa and Cognito User Pool has been configured successfully. In the following directives sending from Alexa, it will contain accessToken in the message body. The accessToken follows the JWT spec. In the backend Lambda, you can verify and decode the JWT token to get the user identity.