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:

1. Clone from the sample repository.
2. Create your Cloud formation stack with this template file.
   
   
    
3. Enter the following stack parameters:
   1. GitHubOwner: The owner of the repository
   2. RepositoryName: The name of your git repository.
   3. BranchName: The branch name of your git repository.
   4. GitHubOAuthToken: Follow the steps in the GitHub documentation to create a new (OAuth 2) token.
   5. VpcId: You can pick the default VPC from drop down, or create your own VPC.

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

1. Alexa requires https endpoints for secure data transactions. You will need to request a SSL certificate or upload your own through AWS Certificate Manager.
   
   
    
2. Once your domain certificate is requested/uploaded, you will need to add HTTPS(443) in load balancer.
   1. Navigate to the Elastic Beanstalk application that you created earlier
   2. Click Configuration → Modify load balancer
   3. Add a new port as shown below:

Step 4: Create an OAuth Client (and Partner) for Your Alexa Skill

1. Log in to the Alexa developer console and select your skill.
2. In the "PERMISSIONS" section, paste your Client Id and Client Secret.
   
   
    
3. In the "ACCOUNT LINKING" section, paste your redirect URLs.
   
   
    
4. Log in to https://YOUR_DOMAIN/ as an administrator. Create an OAuth client that you vend to Alexa (for example, test_alexa_client).
   
   
    
5. (Only for mutual account linking) Log in to https://YOUR_DOMAIN/ as an administrator and create an OAuth partner to call Alexa APIs.
   1. IMPORTANT: clientId and clientSecret are generated by your Alexa Skill (Under the PERMISSION tab). The partnerId should be the same as the "clientId" in the previous step.

Step 5: Update OAuth Endpoints in the Developer Console

1. Log in to Alexa developer console and select your skill.
2. Click "ACCOUNT LINKING" and fill the form with the following:
   
   
    
   • Authorization URI: https://YOUR_DOMAIN/oauth/authorize
   • Access Token URI: https://YOUR_DOMAIN/oauth/token
   • Reciprocal Access Token URI: https://YOUR_DOMAIN/api/reciprocal/authorize
   • Client ID: The clientId of the client you have created in the previous section
   • Client Secret: The clientSecret of the client you created in the previous section
   • Client Authentication Scheme: Select “Credentials in request body” option in the drop down
   • Scope: OAuth scopes to define the permissions (this is used for your resource server, so leave it empty if you do not have one)
   • Domain List: YOUR DOMAIN (for example, for domain.com, this would be www.domain.com)

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:

1. Download and log in to your Alexa app or visit Alexa Web with the same account you used for the developer console.
2. Find your own skill in DEV SKILLS section.
   
   
    
3. Click Enable and you will be redirected to the OAuth server you just set up, where you will need to log in and grant the permission to your Alexa skill.
   
   
   
   
    
4. Once logged in, select Approve to grant the access to your test Alexa skill.
   
   
    
5. Once account linking is completed, you will see a successful linked page.
   
   
    
6. As part of the mutual account linking, Alexa also sends its own OAuth token(LWA) to your OAuth reciprocal endpoint, and can be retrieved from /api/partner/token endpoint.
   1. Get an access token with admin client credential:
      
      
       
   2. Use the access_token you got from previous step to retrieve the LWA token for your Alexa skill.
      
      
       
7. Add Authorization (“Bearer + LWA token”) in request header when you need to interact with Alexa APIs to create/upload your baby health profile(s) for the baby activity skills. Here is a profile example.

{
  "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.