How to add Account Linking in Alexa Skill using Amazon Cognito OAuth2

7 min readJul 22, 2018

Some custom Alexa skills require the ability to connect the identity of the user with a user on their system. This is referred to as account linking, since the goal is to create a link between the Alexa user and the user account in your system.

Account linking leverages OAuth 2.0 an open protocol that provides a simple, standards-based method for web, mobile and desktop applications to request user authorization from remote servers.

As an Alexa skill developer, you could set up and configure your own OAuth server and identity management system. At some large companies, an OAuth server is probably already available and Identity Management procedures already in place. However, at smaller companies, this would require you to build, operate, and maintain your own complex system to manage user identities, passwords, and profiles in a secure and scalable way. Amazon Cognito can help you build your own Identity provider service to achieve the same.

Amazon Cognito User Pools provide a secure user directory that scales to hundreds of millions of users. As a fully managed service, User Pools are easy to set up without any worries about standing up server infrastructure and it leverages industry standards like OAuth 2.0 so it can be easily integrated with your custom backend.

In this blog, we are going to see how to setup Account linking on custom skill with Alexa using your own Identity provider leveraging Amazon Cognito and OAuth2 scopes using Authorize code grant.

Note: If you only want users email ID then we highly recommend you use an OAuth provider like Login with Amazon you can check this blog for step by step instructions.

Account Linking using Amazon Cognito, Step by Step

Follow these steps to configure your Alexa skills with account linking leveraging your own Identity Provider with Amazon Cognito with Mobile OTP login and retrieve the user data from the Access token later.

Step 1: Create AWS Cognito user pool and setup OAuth

Login to AWS Management console and navigate to Cognito service
Select “Manage your user pools” and click “Create a user pool”
Enter a pool name and select “Review defaults”.

· Select Choose username attributes

· And select Email address or phone numbers and choose Allow phone numbers. This is telling Cognito User Pool that we want our users to be able to sign up and login with their phone number as their username. Scroll down and select Next step.

· Here you can setup your password strength policy Obviously requiring a mix of various character types would be more secure, so we can keep it as default, we also want users to be able to sign themselves up so we choose Allow users to sign themselves up. Scroll down and click on Next step

Set multi-factor authentication (MFA) to “Required”

· Check only “Phone number” as a verification method.

· You can keep the “YourPoolName-SMS-Role” (IAM role) that has been filled in as it is and click on “Create Role”. Cognito uses that IAM role to be authorized to send SMS text messages used in MFA.

· Click on “Next Step”

· Hit Review in the side panel and make sure that the Username attributes is set to phone_number.

· Now hit Create pool at the bottom of the page.

· Your User Pool has been created. Note the region that your User Pool is created in — in my case it’s ap-south-1(Mumbai).

We want certain apps to have access to our user pool. In our case Alexa Service for account linking. So, we will create a client for that, steps are as below

· Navigate to “General Settings > App clients” and select “Add an app client”

· Enter a “App client name” and select “Generate client secret” checkbox. Then “Create app client”. Note down the “App client id” and “App client secret” values displayed in next page.

Your app client has been created. Take note of the App client id which will be required later.

· Go to “Domain name” and enter your own domain name. It can be any name like test, test123 etc. You can check if the domain is available or not. Let us assume that domain name is testaccountlinking. So, the URL would be https://testaccountlinking.auth.ap-south-1.amazoncognito.com . Take note of the Amazon cognito domain it will be required later.

Note: To ensure your skill passes certification please ensure to use your own custom domain name.

Step 2: Configure Account Linking in the Alexa Developer Console.

Now that you’ve configured user pool with Amazon Cognito, you can configure Account Linking for your Alexa skill. (Remember, you need to have a skill already created to do this).

Configure your skill with account linking in the developer console in the Build > Account Linking section.

The values you need to enter into these fields are detailed in the table below.

Step 3: Configure Cognito APP client settings

1. Enabled Identity Providers: Cognito User Pools

2. Callback URL(s): https://pitangui.amazon.com/api/skill/link/[vendor-id-amazon-gives-you-in-alexa-config-page]

3. Allowed OAuth Flows: Select Authorization code grant and Implicit grant

4. Allowed OAuth Scopes: Select phone and openid

Step 4: Write your Custom Skill Code.

For the purpose of this blog post, I chose to write the Alexa custom skill code in NodeJS using the ask sdk and deploy it on AWS Lambda.

When your skill is called the first time, you will receive a JSON document where the “user” section contains a userId properties, but no OAuth access token yet as we did not authenticate our user yet. Whenever your code receives such input, it should return a “LinkAccount” card, displayed in the Alexa app or the Alexa web site. The card will contain a link allowing the user to authenticate to your authorization service.

The NodeJS code to generate such an answer inside a LaunchRequest handler might be like:

Step 5: Test Account Linking on Your Skill.

When you invoke your skill from a device, you will receive a card in the Alexa app asking you to link your account. Click on Link Account

When you click “Link account” it opens your Authorization URL configured on Alexa Developer console.

New Users can Sign up and create an account

As we have configured MFA for our userpool, user has to verify their phone number via OTP.

Provide the OTP to Sign in and a confirmation message appears. Voila! your account has now been linked to the skill.

Step 6: Test the Skill Again.

Invoke the skill again. Now, because your account is linked, an Amazon Cognito OAuth Token is included in the input JSON document sent by Alexa. Your code can use this access token to fetch the authenticated user data from USERINFO Endpoint of your Cognito userpool.

Sample Request:

GET https://<your-user-pool-domain>/oauth2/userInfo

Authorization: Bearer <access_token>

Notice the phone number coming as response from the USERINFO API .