How do I add Account linking to my skill?

Summary:

Learn how to link your user’s external accounts to your Alexa skill!

If your skill is relying on access to another system, such as an account based service of your own or even a popular social network, you need a link between the active Amazon account used on the Alexa device and the external account.

To get this working, an access token that uniquely identifies your user must be provided; this is then stored by the Alexa service, and it is included in requests sent to your skill. Thus, the skill can use it to authenticate with the external system. You can either use implicit grant for this, or authorization code grant which you can learn more about online or in our documentation under ‘What Do You Need to Add Account Linking to Your Skill’. OAuth 2.0 specifies 4 roles for this, which is explained further here under OAuth Roles and the Alexa Skills Kit.

Whilst the end-user steps to get account linking remain the same regardless of the method used, please see how the workflow should be for both methods under ‘How End Users Set Up Account Linking for a Skill’ here:

Once setup, you can see what actually happens when a user uses your skill that has been setup for account linking under ‘What Happens when a User Invokes a Skill with Account Linking’ also in our documentation here.

If your skill relies on your own service, you must have a login page that has account linking support. This page must not only validate your user’s credentials, but return an access token or authorization code, and you can see what else is needed here. Check this out for more information on access and refresh tokens.

Code sample / Tips

Account linking is only needed for when authentication is used for the external account.
You must have an account with AWS in regards to the following example.

1. To get started, first login to your developer account, and then under ‘Apps & Services’, go to Alexa and select your skill in ASK. You should then select ‘Yes’ for account linking, and note down the Redirect URL provided

2. Create a Java Server Page (JSP) which only redirects the request to the specified redirect URL found in the developer portal with all of the requested parameters. For example, see the following Implicit Grant example: Account Linking Test

<% String state = request.getParameter("state"); String site = new String( "https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=YOURLINKHERE#state=" + state + "&access_token=SOMESAMPLETOKEN&token_type=Bearer"); response.setStatus(200); response.sendRedirect(site); %>

3. Upload this file to the AWS Elastic Beanstalk and configure HTTPS; for more information, please see this doc: http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/configuring-https.html

4. Back in your skill’s configuration page, put a tick in the Implicit Grant radio button in Authorization Grant Type, and input the URL provided in step 3 as your Authorization URL. In terms of the Client ID and privacy policy URL, this is up to you and depends on your own skill.

5. Go to http://echo.amazon.com/#skills; find your skill here, and you will then see the option to ‘Sign into your account’. If you click it, you will be prompted that the account linking process has been successful

6. Back in the developer portal, go to your skill and then 'Test'. If you then test your skill with the simulator, you should see something like the following in the request:

{
  "session": {
    ...
    "user": {
      "userId": "amzn1.account.AHDAEMZJADOM5YVUR4PZPLKT2XWQ",
      "accessToken": "2YotnFZFEjr1zCsicMWpAA"
    },
    "new": true
  },
  ...
}

7. You have now enabled account linking into your skill!

Relevant Links

Keywords: Account, linking, Alexa, Facebook, Google, Twitter, Echo

KB_0407