With the Alexa Skill Kit (ASK), developers can leverage Amazon’s knowledge in voice design to build quickly and easily. When a developer wants to link the Alexa back end to an external back end that requires authentication, account linking provides a secure way to do that. However, some skill types require the user to mutually link accounts so that skills can send proactive updates to the Alexa back end. This allows customer data to stay in sync across systems and ensures a consistent customer experience across both an Alexa skill and an external app.
Say a customer just welcomed a new baby to their family. They want to start tracking diaper changes and feedings using their voice. You are a developer who has built a baby activity skill using the Baby Activity Skill API. You also offer an app to your customers, and you would like to present them with a consistent experience across both your Alexa skill and your app. A customer can start by adding a new profile with the baby’s name in the app that corresponds to your skill. But Alexa needs to know about this update too! Mutual account linking allows the corresponding app to send a health profile update to Alexa.
Most OAuth servers only provide the ability to authenticate and authorize users in the skill developers' system. However, some skills, like Baby Activity Skills, must proactively interact with the Alexa backend to make updates. In Alexa, this is achieved by a reciprocal authorization endpoint, which is hosted by the skill developer to obtain the auth_code from Alexa. This blog post will show you how to use the sample code to enable mutual account linking with your Alexa skill. We provide an example of account linking with OAuth 2.0, and an example that leverages a reciprocal authorization endpoint as an additional step for mutual account linking.
Prerequisites
In order to complete the steps in this blog post you will need the following:
- An AWS account. Log in or Sign up.
- An Amazon developer account. Log in or Sign up.
- A basic understanding of Amazon Alexa skill development.
Step 1: Set up an OAuth Server
To help skill developers implement their own OAuth server, we have provided a repository with OAuth sample code (based on Spring Security), necessary infrastructure based on AWS Cloud Formation (to help set up a web service on AWS Elastic Beanstalk), a set of AWS DynamoDB tables to store tokens, and an AWS Code Pipeline to help you build and deploy code from your Github repository. Follow these steps to set up your server:
After following these steps, you will have generated the following endpoints:
- /oauth/authorize: The authorization endpoint is the endpoint on the authorization server where the resource owner logs in and grants authorization to the client application.
- /oauth/token: The token endpoint is the endpoint on the authorization server where the client application exchanges the authorization code, client ID, and client secret for an access token.
- /api/reciprocal/authorize: The reciprocal authorization endpoint will be invoked by Alexa to send a LWA auth code (only required for mutual account linking).
- /api/partner/token: The endpoint to refresh/obtain a partner token (e.g. LWA token) saved in your system.
Step 2: Integrate with Your Identity Provider
- Test your identity provider with a mock user. We have provided the following mock user for testing:
- {username: admin, password: password}: a user with Administration Role.
- {username: user, password: password}: a user with Normal Role.
Once completed, you are ready to verify the user identity in your own system.
- Customize the AuthenticationServiceProvider.java class by overriding the following method.
public UserDetails loadUserByUsername(final String username) throws UsernameNotFoundException {
//TODO: Integrate with your authentication system in replace the mock users.
}Step 3: Bind Your SSL Certificate to Your HTTPS Endpoint
Step 4: Create an OAuth Client (and Partner) for Your Alexa Skill
Step 5: Update OAuth Endpoints in the Developer Console
Step 6:Test Your Alexa Skill
After you have linked Alexa with your OAuth server in developer console, test your skill by following these steps:
{
"report": {
"messageId": "<message id>",
"profiles": [
{
"profileId": "<profile id>",
"name": {
"firstName": "John",
"lastName": "Doe"
},
"capabilities": [
{
"name": "Alexa.Health.Weight",
"type": "AlexaInterface",
"version": "1",
"supportedOperations": ["Add", "Delete", "Get"]
},
{
"name": "Alexa.Health.Sleep",
"type": "AlexaInterface",
"version": "1",
"supportedOperations": ["Add", "Delete", "Get"]
}
]
}
]
}
}
Conclusion
Congratulations! Your customers will now have a consistent experience across your Alexa skill and your app. You have created your own OAuth server to securely communicate with the Alexa backend system when your customers link accounts with Alexa. In addition, you have hosted a reciprocal authorization endpoint to proactively interact with the Alexa backend.
Try the Baby Activity Skill API Today
Now, when customers welcome a new member to their family, the change they make to their profile in the app will automatically be reflected in their corresponding Alexa skill. Review our documentation to get started. We are excited for you to leverage the power of voice to further increase the value of your services for your customers.