6. Setup Alexa Account Linking

This article describes how to create Account Linking between developer’s account system and Amazon account system. Account linking could distinguish different users similar with APP’s login function and by this, you could provide personal information’s interaction.

In this lab, Amazon Cognito User Pool will be used as the developer’s account system. Cognito helps developer 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

If you already know Account linking, please go straight to Configure App Client OAuth 2.0 Settings

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.

Auth-Code-Flow

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.

Flow

Configure App Client OAuth 2.0 Settings

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

  1. Go to Cognito User Pool Console

  2. On the left side navigation bar, under App integration, select App client settings

  3. Find the App Client created in Create a Cognito User Pool Client, if you followed the guide, it should be named alexa

  4. Under Enabled Identity Providers，select Cognito User Pool

  5. 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.

  6. In Allowed OAuth Flows session，choose Authorization code grant

  7. In Allowed OAuth Scopes session，choose openid

  8. 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.

  1. Go to Cognito User Pool Console

  2. On the left side bar, under App integration, choose Domain name

  3. Enter domain prefix and click Check availability, the domain name must be unique

  4. When promoted the domain is available，choose Save changes

Configure Account Linking in Alexa Developer Console

  1. Go to Alexa Console

  2. In the Skills list，choose the previously created skill

  3. On the left side navigation bar，choose Account Linking

  4. Under Security Provider Information，choose Auth Code Grant

  5. Enter https://<your-cognito-domain>/oauth2/authorize in Authorization URI

  6. Enter https://<your-cognito-domain>/oauth2/token in Access Token URI

  7. Enter Client ID and Client Secret, you can find in them in Cognito User Pool console, under App Clients section

  8. Click Add scope and input openid. For Smart Home skill, at least one scope should be specified

  9. 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.

  1. Launch Alexa APP on mobile phone

  2. Click the button on the top left corner

  3. Choose Skills & Games, then click Your Skills

  4. click the DEV in the sliding window.

  5. Your created Smart Home Skill SmartLamp should be listed below. Click it to continue.

  6. Click the Enable To Use button

  7. On the popup window, input your email and password, if have not registered yet, sign up one

  8. 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.

Reference

Understand Account Linking

The OAuth2.0 Authorization Framework

JSON Web Token

AWS Cognito User Pool