In part one of this blog series, we reviewed the different options for personalizing your skill’s experience through the use of the Customer Contact, Device Location, Device Settings, and Location Services APIs, as well as through account linking.
This tutorial guides you through the creation and configuration of an Amazon Cognito User Pool and provides sample skill code which will be configured to make use of the Cognito User Pool as an OAuth authorization and service end-point. During this walk through, we'll go over:
If the Cognito feature of additional user attributes/properties is not required, consider using Login with Amazon.
The Linked Profile sample custom skill demonstrates account linking for the purposes of utilizing a linked profile. While any compliant OAuth identity provider could be used with account linking, this sample will use Amazon Cognito.
These instructions will cover how to set up a user account and OAuth service using Amazon Cognito User Pools, coupled with an example skill (written using the Alexa Skills Kit (ASK) SDK and AWS SDK for Node.js) that links to the Cognito OAuth service and provides personalized responses.
This sample is a starting point for skill developers who may not have existing user accounts or OAuth infrastructure already in place.
Note: The Amazon Cognito configuration provided in this tutoral does not constitute a full solution for user account management and OAuth.
In order to completely set up this sample, the following are required:
Amazon Cognito User Pool
How the Amazon Cognito User Pool works:
Customers will authenticate directly with the Cognito user portal when linking the skill using the Alexa app. The specific sequence of events which happen when the account linking process happens is shown in the following diagram.
How Account Linking works with Amazon Cognito User Pools:
22. Copy/paste the comma-separated Callback URL list into the Callback URL(s) field.
23. Further down the same page, under OAuth 2.0 and Allowed OAuth Flows, check the box titled Authorization code grant.
24. Under Allowed OAuth Scopes, check these boxes:
The openid scope returns all user attributes in the ID token that are readable by the client. The ID token is not returned if the openid scope is not requested by the client.
The aws.cognito.signin.user.admin scope grants access to Amazon Cognito User Pool API operations that require access tokens.
The profile scope grants access to all user attributes that are readable by the client. Note: Phone and email are included in the profile scope, so there’s no need to check these boxes.
25. Click Save changes.
There are two options for setting your Cognito OAuth domain:
Note: You need to own the OAuth domain if you wish to publish a skill (or skills) that uses this OAuth system.
Since you are just trying this out, you can use a Cognito domain.
If you are unsure about the management of SSL certificates for your domain, contact your network administrator. This sample assumes you have a domain managed by Amazon Route 53. Domains managed elsewhere may have different steps, which are outside the scope of this sample.
You have now created a User Pool and are ready to move on to the next step of creating the AWS IAM role which will be used by the AWS Lambda function that backs your skill.
In this section, you will create an AWS IAM Role (with policy) which will be used by the Lambda function that backs your skill.
6. Click Review Policy.
7. Enter a name such as linked-profile-skill-policy.
8. Click Create policy.
9. Select Roles on the left-side menu.
10. Click the Create role button.
11. Under Select type of trusted entity, select AWS service.
12. Under Choose the service that will use this role, select Lambda.
13. Click the Next:Permissions button.
14. Search for the policy (linked-profile-skill-policy) created in an earlier step and check the box next to your policy.
15. Click the Next:Tags button, then the Next:Review button.
16. Enter a name such as linked-profile-role.
17. Click the Create role button.
18. Copy the role name to your Scratch-Pad. You will need this later in the process.
In this section, you will create a skill configured to support account linking with the Cognito system created earlier.
The simplest way to create a user is to do so via the account linking process in the Alexa website.
If you verified the test account using the verification code, skip to the next section.
open link demo
what is my name
what is my number
what’s my address
what is my email
Note: You can also test these utterances out using a device associated with your Developer Account or from the ASK CLI using either the ask simulate or ask dialog commands.
Congratulations! You should have successfully created a Cognito User Pool, a skill that uses that pool, a user in that pool, and linked the skill with that account.
This sample can be something you're going to use just for learning, or as the basis for a skill you're building to work with Alexa for Business or for the Alexa Skill Store. Whatever is next, we look forward to seeing what you build!