{"id":17145,"date":"2018-01-25T19:51:00","date_gmt":"2018-01-25T19:51:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/premier_developer\/?p=17145"},"modified":"2019-07-29T12:14:13","modified_gmt":"2019-07-29T19:14:13","slug":"amazon-alexa-skills-authenticated-by-azure-active-directory-and-backed-by-an-azure-function","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/premier-developer\/amazon-alexa-skills-authenticated-by-azure-active-directory-and-backed-by-an-azure-function\/","title":{"rendered":"Amazon Alexa Skills authenticated by Azure Active Directory and backed by an Azure Function"},"content":{"rendered":"

This post is provided by Premier Field Engineer, Nathan Vanderby<\/a>, who walks us through how to write an Alexa skill using Azure Functions.\u00a0 Last updated June 2018.<\/strong><\/p>\n

\n

Most people have heard of the Amazon Echo and the skills that provide it functions. Amazon makes it really easy to create these skills using an AWS Lambda function. These can also be backed using a REST API app<\/a> or even an Azure Function. Below we will give some instructions for how to leverage Azure Functions. The steps below are almost identical to how you would configure a generic backend API with authentication except that the Azure Function needs to manually verify the JWT token instead of leveraging the [Authorize]<\/code> attribute.<\/p>\n

Step-by-step tutorial<\/h4>\n
Step 1: Create an Azure Subscription<\/h5>\n

If you haven’t already signed up for Azure you can do so here<\/a>. We will use Azure AD for app registration and Azure Functions for the backend. Azure Functions creates a storage account and App. Service resources with it. The cost of doing a proof of concept should be minimal given the app registrations are free, we won’t be using the storage account and Azure Functions give 400,000 GB-s<\/a> free each month.<\/p>\n

Step 2: Create your Azure Function<\/h5>\n

We will start off by using the Azure Functions<\/strong> new project template in Visual Studio. This tutorial focuses on C#, but it is also possible to develop Azure Functions on any platform<\/a>.\n\"\"<\/p>\n

Make sure your project is at least on .NET Framework 4.6.1. This is due to the Alexa.Net<\/a> NuGet package we will use to deserialize the Alexa JSON to classes. This will require us to use the Azure Function 2.x runtime version<\/a>.<\/p>\n

Once your project is created add a new Azure Function<\/strong> item to it.\n\"\"<\/p>\n

Set the trigger type to Http trigger<\/strong> and the access rights to Anonymous<\/strong>.\n\"\"<\/p>\n

This will give us a default Run method that is attributed such that the Azure function name is what you specified in the wizard (Alexa in this case). It also sets up anonymous authorization with get and post REST methods. The inputs to the method is an HttpRequestMessage and a TraceWriter.<\/p>\n

Add the Alexa.NET<\/strong> NuGet Package (https:\/\/github.com\/timheuer\/alexa-skills-dotnet<\/a>) to the project so we can easily deserialize the JSON into classes.\n\"\"<\/p>\n

Now we can add some code. First modify the method signature. We can remove the get<\/code> REST API and we can leverage the [FromBody]<\/code> attribute to easily deserialize the JSON into a SkillRequest<\/code>. Then add some code to respond to a skill request. The code below simply looks for a first name and responds with “Hello [FirstName]”.<\/p>\n

[FunctionName(\"Alexa\")]\r\npublic static async Task<SkillResponse> Run(\r\n    [HttpTrigger(AuthorizationLevel.Anonymous, \"post\", Route = null)]\r\n    [FromBody]SkillRequest request, TraceWriter log)\r\n{\r\n    SkillResponse response = null;\r\n    PlainTextOutputSpeech outputSpeech = new PlainTextOutputSpeech();\r\n    string firstName = (request.Request as IntentRequest)?.Intent.Slots.FirstOrDefault(s => s.Key == \"FirstName\").Value?.Value;\r\n    outputSpeech.Text = \"Hello \" + firstName;\r\n    response = ResponseBuilder.Tell(outputSpeech);\r\n    return response;\r\n} \r\n<\/code><\/pre>\n
This code will work as an unauthenticated backend for an Alexa skill. Lets publish it and test it, then circle back to add authentication.<\/p>\n
Step 3: Publish to Azure<\/h5>\n
To push the code to Azure simply right click on the project and select Publish<\/strong>. Walk through the wizard to create a new Azure Function or select from one that has been already created.<\/p>\n
Once the Azure function is created we need to change the runtime version to V2. Go to portal.azure.com<\/a> and navigate to the function you are using. From the Overview<\/strong> pane select Function app settings<\/strong>.\n\"\"<\/p>\n
 <\/p>\n
Inside the app settings change the Runtime version<\/strong> to be at least 2.0, currently this is the beta. This is only required since we are leveraging a NuGet that is build for .NET Standard 1.6. If you write your own library or use a different one that is compatible with .NET Framework 4.5 this is not necessary.\n\"\"<\/p>\n
Now you should be able to return to Visual Studio and publish your function to Azure. Once your publish is successful you will want to go back to Azure, select that function and copy its URL for use in configuring the Alexa skill.\n\"\"<\/p>\n
Step 4: Configure the Alexa Skill<\/h5>\n
Now that we have our code in Azure we need to configure the Alexa skill. Navigate to Amazon’s developer<\/a> page for Alexa, you will have to create an account. Navigate to Alexa Skills Kit -> Get Started -> Alexa Skills Kit<\/strong>.\n\"\"<\/p>\n
Select Start a Skill<\/strong> then Create Skill<\/strong>.<\/p>\n
Give the skill a name, click next. Select the Custom<\/strong> model then click Create Skill<\/strong>.<\/p>\n
Invocation<\/h6>\n
Select Invocation<\/strong> and enter a phrase to invoke your skill. Click Save<\/strong> then Next<\/strong> to move onto the Interaction Model.\n\"\"<\/p>\n
Intents<\/h6>\n
Select the Add<\/strong> button next to Intents<\/strong> and give the intent a name. We will use Tutorial.\n\"\"<\/p>\n
Type in a sample utterance such as Can you greet {FirstName}<\/code> and click Add<\/strong> to create the sample utterance and the FirstName<\/code> slot.\n\"\"<\/p>\n
The intent here is so Alexa knows that when we talk to “Tutorial” it should also expect a parameter called FirstName. If you look back at the code in the API Post method you will see how we can read the FirstName slot from the Tutorial intent on the request.<\/p>\n
Make sure the FirstName<\/code> slot has a type of Amazon.DE_FIRST_NAME<\/code>.\n\"\"<\/p>\n
In the JSON Editor your skill should look like<\/p>\n
{\r\n    \"interactionModel\": {\r\n        \"languageModel\": {\r\n            \"invocationName\": \"Tutorial\",\r\n            \"intents\": [\r\n                {\r\n                    \"name\": \"Tutorial\",\r\n                    \"slots\": [\r\n                        {\r\n                            \"name\": \"FirstName\",\r\n                            \"type\": \"AMAZON.DE_FIRST_NAME\"\r\n                        }\r\n                    ],\r\n                    \"samples\": [\r\n                        \"Can you greet {FirstName}\"\r\n                    ]\r\n                },\r\n                {\r\n                    \"name\": \"AMAZON.HelpIntent\",\r\n                    \"samples\": []\r\n                },\r\n                {\r\n                    \"name\": \"AMAZON.StopIntent\",\r\n                    \"samples\": []\r\n                }\r\n            ],\r\n            \"types\": []\r\n        }\r\n    }\r\n}\r\n<\/code><\/pre>\n
Click Save Model<\/strong> and then Build Model<\/strong><\/p>\n
Interfaces<\/h5>\n
Here you can add various interfaces. We won’t be using any of these. The various options for these are Audio Player, Display Interface, Video App, Alexa Gadget, etc.<\/p>\n
Endpoint<\/h6>\n
Select HTTPS<\/strong> for the endpoint. Under the Default Region<\/strong> text box enter the URL for your Azure function.\n\"\"<\/p>\n
Select My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority<\/strong> from the drop down.<\/p>\n
Test<\/h6>\n
In this page take note of the URL you are sending an Alexa request to and simply type in an utterance such as Tutorial can you greet Nate.<\/strong> You should get a service response.\n\"\"<\/p>\n
Now that our skill is working we need to add authentication to it.<\/p>\n
Step 5: Configure Azure Active Directory<\/h5>\n
App Registration<\/h6>\n
Go to the Azure portal and find the Azure Active Directory service. Then click on App registrations<\/strong> and New application registration<\/strong>.\n\"\"<\/p>\n
Give your registration and name, select Web app\/API<\/strong> as its type and give it a sign-on URL. This URL doesn’t matter for this tutorial.\n\"\"<\/p>\n
Now that the app registration is created select All settings<\/strong> then Properties<\/strong>. Note the App ID URI<\/strong> value. We will need this value later on in the C#.\n\"\"<\/p>\n
Lastly, make note of the Keys<\/strong> property. We will have to come back here later to generate a key as a part of the Alexa account linking configuration.<\/p>\n
That\u2019s it for now. We\u2019ll come back to the app registration later to update the Redirect URI and get a Client Secret (aka Key) as a part of configuring the account linking in the Alexa skill configuration.<\/p>\n
Step 6: Adding Authentication in the Code<\/h5>\n
There are a few posts out there for performing token authentication without leveraging ASP.NET middleware. One of the most helpful and relevant to Azure Functions comes from Boris Wilhelms<\/a>. I have leveraged his code sample below.<\/p>\n
Create a class called Security and copy from the code below. This code is definitely sample code and not<\/strong> production ready. The two main variables to set are the ISSUER<\/code> and AUDIENCE<\/code>. The GUID for the issuer is your AAD directory ID that you can get from the properties section of the Azure AD resource. The audience value comes from the App ID URI. The code below also requires 2 additional NuGet packages. The first is System.IdentityModel.Tokens.Jwt<\/code> v5.1.4<\/strong> or lower. The second is Microsoft.IdentityModel.Protocols.OpenIdConnect<\/code> v2.1.4<\/strong> or lower. At the time of writing this if you use versions 5.1.5 or 2.1.5 respectively a runtime error occurs when Azure tries to load the function.<\/p>\n
public static class Security\r\n{\r\n\tprivate static readonly string ISSUER = \"https:\/\/sts.windows.net\/XXXXXXXX-XXXX-XXXX-aec1-f1f2a290f738\/\";\r\n\tprivate static readonly string AUDIENCE = \"https:\/\/AlexaToAzure.onmicrosoft.com\/AlexaBackendAPI\";\r\n\tprivate static readonly IConfigurationManager<OpenIdConnectConfiguration> _configurationManager;\r\n\r\n\tstatic Security()\r\n\t{\r\n\t\tHttpDocumentRetriever documentRetriever = new HttpDocumentRetriever();\r\n\t\tdocumentRetriever.RequireHttps = ISSUER.StartsWith(\"https:\/\/\");\r\n\r\n\t\t_configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(\r\n\t\t\t$\"{ISSUER}\/.well-known\/openid-configuration\",\r\n\t\t\tnew OpenIdConnectConfigurationRetriever(),\r\n\t\t\tdocumentRetriever);\r\n\t}\r\n\r\n\tpublic static async Task<ClaimsPrincipal> ValidateTokenAsync(string value)\r\n\t{\r\n\t\tvar config = await _configurationManager.GetConfigurationAsync(CancellationToken.None);\r\n\t\tvar issuer = ISSUER;\r\n\t\tvar audience = AUDIENCE;\r\n\r\n\t\tvar validationParameter = new TokenValidationParameters()\r\n\t\t{\r\n\t\t\tRequireSignedTokens = true,\r\n\t\t\tValidAudience = audience,\r\n\t\t\tValidateAudience = true,\r\n\t\t\tValidIssuer = issuer,\r\n\t\t\tValidateIssuer = true,\r\n\t\t\tValidateIssuerSigningKey = true,\r\n\t\t\tValidateLifetime = true,\r\n\t\t\tIssuerSigningKeys = config.SigningKeys\r\n\t\t};\r\n\r\n\t\tClaimsPrincipal result = null;\r\n\t\tvar tries = 0;\r\n\r\n\t\twhile (result == null && tries <= 1)\r\n\t\t{\r\n\t\t\ttry\r\n\t\t\t{\r\n\t\t\t\tvar handler = new JwtSecurityTokenHandler();\r\n\t\t\t\tresult = handler.ValidateToken(value, validationParameter, out var token);\r\n\t\t\t}\r\n\t\t\tcatch (SecurityTokenSignatureKeyNotFoundException)\r\n\t\t\t{\r\n\t\t\t\t\/\/ This exception is thrown if the signature key of the JWT could not be found.\r\n\t\t\t\t\/\/ This could be the case when the issuer changed its signing keys, so we trigger a \r\n\t\t\t\t\/\/ refresh and retry validation.\r\n\t\t\t\t_configurationManager.RequestRefresh();\r\n\t\t\t\ttries++;\r\n\t\t\t}\r\n\t\t\tcatch (SecurityTokenException)\r\n\t\t\t{\r\n\t\t\t\treturn null;\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\treturn result;\r\n\t}\r\n}\r\n<\/code><\/pre>\n
Next we have to modify the Run<\/code> method to call into this `ValidateTokenAsyn()“ with the Alexa requests access token.<\/p>\n
SkillResponse response = null;\r\nif (request?.Session?.User?.AccessToken != null)\r\n{\r\n\tClaimsPrincipal principal = await Security.ValidateTokenAsync(request.Session.User.AccessToken);\r\n\tif (principal != null)\r\n\t{\r\n\t\tPlainTextOutputSpeech outputSpeech = new PlainTextOutputSpeech();\r\n\t\tstring firstName = (request.Request as IntentRequest)?.Intent.Slots.FirstOrDefault(s => s.Key == \"FirstName\").Value?.Value;\r\n\t\toutputSpeech.Text = \"Hello \" + firstName;\r\n\t\tresponse = ResponseBuilder.Tell(outputSpeech);\r\n\t}\r\n}\r\n\r\nreturn response;\r\n<\/code><\/pre>\n
Publish this new code to your Azure Function and navigate to the Amazon developer portal to configure the Alexa skill for account linking.<\/p>\n
Step 7: Alexa Account Linking Configuration<\/h5>\n
Navigate back to the Alexa skill page. In the Account Linking section enable the slider. Enter the following information into the fields:<\/p>\n