Account Linking : Amazon Alexa and ForgeRock OpenAM using OAuth2 Authorization grant

In this blog, we are going to setup Account Linking between a Alexa Skill and ForgeRock OpenAM using OAuth2 Authorization grant. To know more about Alexa Account Linking, refer this link.

Below is the flow diagram :

1. User invokes a skill in Alexa device, say Echo
2. Echo will invoke the Alexa service
3. Alexa service will identify the correct skill depending on user’s request and send a request to the Alexa skill
4. Alexa skill will identify the correct intent and forward the request to Lambda function along with the access_token if it already exists
5. Lambda function will retrieve the access_token from the request and validate against OpenAM using tokeninfo endpoint
6. If the access_token is still valid, OpenAM will return the user attributes. If not, OpenAM will return 401
7. Depending on the validity of the token, Lambda function will return a Simple Card or a LinkAccount card

8a. If the access_token is valid, a Simple Card will be returned with some message

8a1. Alexa service will process the message and convert it into a format that Echo device can understand

8a2. Echo device will play the message

8b. If the access_token is not present or invalid, a LinkAccount card will be returned to Alexa service

8b1. Alexa service will automatically notify the Alexa Mobile App to show the LinkAccount screen for this particular skill

8b2. Alexa mobile app will show a LinkAccount link

8b3. User can click this click which in turn will initiate a OAuth2 Authorization code grant flow with OpenAM

8b4. If the user authenticates successfully, Alexa will receive a access_token, refresh_token pair and show a message to the user saying account linking is successful.

9. User can again invoke the same skill using voice command and this time Lambda function will have a valid access_token to process the message.

There are few prerequisites to setup Account Linking between Alexa and OpenAM

1. Knowledge on AWS services like Lambda, Alexa
2. Knowledge on Java and AWS SDK
3. A fully functioning OpenAM environment which can be accessed through internet with https. Let us assume that it is https://openam.example.com/auth. Please replace this value with a valid OpenAM URL.

Step 1 : Setup HelloWorld Alexa Skill

Follow this link to setup HelloWorld Alexa Skill. You can test the skill using Alexa Skills Kit Developer Console as mentioned in that article.

Step 2 : Create a new intent with LinkAccount card

• Create a new java class to handle ForgeRock intent with LinkAccount card. Copy the below source and place it in the same package com.amazon.ask.helloworld.handlers as other Java classes.

• If you are using eclipse, your project should look like below. All the other classes are from the HelloWorld sample skill

• Follow this link to configure and test your skill. For this skill, name it as “ForgeRock-skill”. Please note that you need to recompile and build the jar file to include the new class file. Also, upload the latest jar to Lambda function.
• Please note that you have to add a new Environment variable in Lambda function. This value will be used by the ForgeRockIntentHandler class to make a token validation call to OpenAM.

• Use the below intent json instead of the one mentioned in that tutorial. I added a new intent “ForgeRockIntent”

• You can paste this entire json content in Alexa JSON Editor and save the changes.

• Please note that whenever you change some settings, don’t forget to save and build the model again using “Save Model” and “Build Model” buttons. Otherwise, new changes won’t take effect when you invoke the skill.

Step 3 : Create a new agent in ForgeRock OpenAM for this skill

• Login to ForgeRock OpenAM console and create a new OAuth agent called “fragent” .

• Those “Redirection URIs” are from Alexa skill “Account Linking” configuration.

• If you scroll down, you will see those URLs. Copy those URLs and configure in OpenAM OAuth agent.

• Also, make sure you set the default scope for fragent to cn and sn

Step 4 : Configure Account Linking in Alexa Skill

• Go to “Account Linking” and enable that option.
• Also, enter the OpenAM “Authorization URI”, “Access Token URI”, OAuth agent “Client ID” and “Client Secret”

• For “Client Authentication Scheme”, select “Credentials in request body” . Even though “HTTP Basic” is the recommended approach, somehow it didn’t work with OpenAM

Step 5 : Testing the skill

• Navigate to “Test” tab and type “tell greeter hello”. It should respond back with “Hello World”

• Now, type “tell greeter forgerock” and it should respond back with a message saying you should link your Alexa account with ForgeRock account because ForgeRockIntent requires a valid access_token.

• If you open your Alexa Mobile app, it should automatically show the below screen in home page

• If you click “LINK ACCOUNT”, it will open a browser and initiate OAuth2 Authorization Code Grant flow with ForgeRock. Login with a valid user credentials and it will redirect you back to below page saying account is linked successfully.

• Now, go back to “Test” screen and type “tell greeter forgerock”. Alexa will respond back with “Welcome <your full name : cn attribute value>” followed by a brief description of ForgeRock product.

• When you invoked the same intent again, Alexa had a valid access_token for this user. Hence, the ForgeRockIntentHandler class was able to invoke OpenAM’s /oauth2/tokeninfo URL to retrieve the user’s cn and sn attribute values using the access_token. The “cn” value is appended to the message.

We have successfully setup Account Linking between Amazon Alexa and ForgeRock OpenAM. Since Alexa uses OAuth2 for Account Linking, it gives us more flexibility in terms of designing the solution. Let’s say the Alexa skill has to invoke some API which is exposed using API Gateway. We can use the same access_token to protect those APIs too.

Thanks for reading this blog. If you have any questions / suggestions, kindly leave a comment.