Imagine that you want to create
a Metro style app written with JavaScript and you want to communicate with
a remote web service. For example, you are creating
a movie app which retrieves
a list of movies from
a movies service. In this situation, how do you authenticate your Metro app and the Metro user so not just anyone can call the movies service? How can you identify the user making the request so you can return user specific data from the service?
The Windows Live SDK supports
a feature named Single Sign-On. When
a user logs into
a Windows 8 machine using their Live ID, you can authenticate the user’s identity automatically. Even better, when the Metro app performs
a call to
a remote web service, you can pass an authentication token to the remote service and prevent unauthorized access to the service.
The documentation for Single Sign-On is located here:
http://msdn.microsoft.com/en-us/library/live/hh826544.aspx
In this blog entry, I describe the steps that you need to follow to use Single Sign-On with
a (very) simple movie app. We build
a Metro app which communicates with
a web service created using the ASP.NET Web API.
Creating the Visual Studio Solution
Let’s start by creating
a Visual Studio solution which contains two projects:
a Windows Metro style Blank App project and an ASP.NET MVC 4 Web Application project. Name the Metro app MovieApp and the ASP.NET MVC application MovieApp.Services. When you create the ASP.NET MVC application, select the Web API template:
After you create the two projects, your Visual Studio Solution Explorer window should look like this:
Configuring the Live SDK
You need to get your hands on the Live SDK and register your Metro app. You can download the latest version of the SDK (version 5.2) from the following address:
http://www.microsoft.com/en-us/download/details.aspx?id=29938
After you download the Live SDK, you need to visit the following website to register your Metro app:
https://manage.dev.live.com/build
Don’t let the title of the website — Windows Push Notifications & Live Connect – confuse you, this is the right place. Follow the instructions at the website to register your Metro app. Don’t forget to follow the instructions in Step 3 for updating the information in your Metro app’s manifest.
After you register, your client secret is displayed. Record this client secret because you will need it later (we use it with the web service):
You need to configure one more thing. You must enter your Redirect Domain by visiting the following website:
https://manage.dev.live.com/Applications/Index
Click on your application name, click Edit Settings, click the API Settings tab, and enter
a value for the Redirect Domain field. You can enter any domain that you please just as long as the domain has not already been taken:
For the Redirect Domain, I entered http://superexpertmovieapp.com.
Create the Metro MovieApp
Next, we need to create the MovieApp. The MovieApp will:
1. Use Single Sign-On to log the current user into Live
2. Call the MoviesService web service
3. Display the results in
a ListView control
Because we use the Live SDK in the MovieApp, we need to add
a reference to it. Right-click your References folder in the Solution Explorer window and add the reference:
Here’s the HTML page for the Metro App:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>MovieApp</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.1.0.RC/css/ui-dark.css" rel="stylesheet" />
<script src="//Microsoft.WinJS.1.0.RC/js/base.js"></script>
<script src="//Microsoft.WinJS.1.0.RC/js/ui.js"></script>
<!-- Live SDK -->
<script type="text/javascript" src="/LiveSDKHTML/js/wl.js"></script>
<!-- WebServices references -->
<link href="/css/default.css" rel="stylesheet" />
<script src="/js/default.js"></script>
</head>
<body>
<div id="tmplMovie"
data-win-control="WinJS.Binding.Template">
<div class="movieItem">
<span data-win-bind="innerText:title"></span>
<br /><span data-win-bind="innerText:director"></span>
</div>
</div>
<div id="lvMovies"
data-win-control="WinJS.UI.ListView"
data-win-options="{
itemTemplate: select('#tmplMovie')
}">
</div>
</body>
</html>
The HTML page above contains
a Template and ListView control. These controls are used to display the movies when the movies are returned from the movies service.
Notice that the page includes
a reference to the Live script that we registered earlier:
<!-- Live SDK -->
<script type="text/javascript" src="/LiveSDKHTML/js/wl.js"></script>
The JavaScript code looks like this:
(function () {
"use strict";
var REDIRECT_DOMAIN = "http://superexpertmovieapp.com";
var WEBSERVICE_URL = "http://localhost:49743/api/movies";
function init() {
WinJS.UI.processAll().done(function () {
// Get element and control references
var lvMovies = document.getElementById("lvMovies").winControl;
// Login to Windows Live
var scopes = ["wl.signin"];
WL.init({
scope: scopes,
redirect_uri: REDIRECT_DOMAIN
});
WL.login().then(
function(response) {
// Get the authentication token
var authenticationToken = response.session.authentication_token;
// Call the web service
var options = {
url: WEBSERVICE_URL,
headers: { authenticationToken: authenticationToken }
};
WinJS.xhr(options).done(
function (xhr) {
var movies = JSON.parse(xhr.response);
var listMovies = new WinJS.Binding.List(movies);
lvMovies.itemDataSource = listMovies.dataSource;
},
function (xhr) {
console.log(xhr.statusText);
}
);
},
function(response) {
throw WinJS.ErrorFromName("Failed to login!");
}
);
});
}
document.addEventListener("DOMContentLoaded", init);
})();
There are two constants which you need to set to get the code above to work: REDIRECT_DOMAIN and WEBSERVICE_URL. The REDIRECT_DOMAIN is the domain that you entered when registering your app with Live. The WEBSERVICE_URL is the path to your web service.
You can get the correct value for WEBSERVICE_URL by opening the Project Properties for the MovieApp.Services project, clicking the Web tab, and getting the correct URL. The port number is randomly generated. In my code, I used the URL “http://localhost:49743/api/movies”.
Assuming that the user is logged into Windows 8 with
a Live account, when the user runs the MovieApp, the user is logged into Live automatically. The user is logged in with the following code:
// Login to Windows Live
var scopes = ["wl.signin"];
WL.init({
scope: scopes,
redirect_uri: REDIRECT_DOMAIN
});
WL.login().then(function(response) {
// Do something
});
The scopes setting determines what the user has permission to do. For example, access the user’s SkyDrive or access the user’s calendar or contacts. The available scopes are listed here:
http://msdn.microsoft.com/en-us/library/live/hh243646.aspx
In our case, we only need the wl.signin scope which enables Single Sign-On.
After the user signs in, you can retrieve the user’s Live authentication token. The authentication token is passed to the movies service to authenticate the user.
Creating the Movies Service
The Movies Service is implemented as an API controller in an ASP.NET MVC 4 Web API project. Here’s what the MoviesController looks like:
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using JWTSample;
using MovieApp.Services.Models;
namespace MovieApp.Services.Controllers
{
public class MoviesController : ApiController
{
const string CLIENT_SECRET = "NtxjF2wu7JeY1unvVN-lb0hoeWOMUFoR";
// GET api/values
public HttpResponseMessage Get()
{
// Authenticate
// Get authenticationToken
var authenticationToken = Request.Headers.GetValues("authenticationToken").FirstOrDefault();
if (authenticationToken == null)
{
return new HttpResponseMessage(HttpStatusCode.Unauthorized);
}
// Validate token
var d = new Dictionary<int, string>();
d.Add(0, CLIENT_SECRET);
try
{
var myJWT = new JsonWebToken(authenticationToken, d);
}
catch
{
return new HttpResponseMessage(HttpStatusCode.Unauthorized);
}
// Return results
return Request.CreateResponse(
HttpStatusCode.OK,
new List<Movie> {
new Movie {Title="Star Wars", Director="Lucas"},
new Movie {Title="King Kong", Director="Jackson"},
new Movie {Title="Memento", Director="Nolan"}
}
);
}
}
}
Because the Metro app performs an HTTP GET request, the MovieController Get() action is invoked. This action returns
a set of three movies when, and only when, the authentication token is validated.
The Movie class looks like this:
using Newtonsoft.Json;
namespace MovieApp.Services.Models
{
public class Movie
{
[JsonProperty(PropertyName="title")]
public string Title { get; set; }
[JsonProperty(PropertyName="director")]
public string Director { get; set; }
}
}
Notice that the Movie class uses the JsonProperty attribute to change Title to title and Director to director to make JavaScript developers happy.
The Get() method validates the authentication token before returning the movies to the Metro app. To get authentication to work, you need to provide the client secret which you created at the Live management site. If you forgot to write down the secret, you can get it again here:
https://manage.dev.live.com/Applications/Index
The client secret is assigned to
a constant at the top of the MoviesController class.
The MoviesController class uses
a helper class named JsonWebToken to validate the authentication token. This class was created by the Windows Live team. You can get the source code for the JsonWebToken class from the following GitHub repository:
https://github.com/liveservices/LiveSDK/blob/master/Samples/Asp.net/AuthenticationTokenSample/JsonWebToken.cs
You need to add an additional reference to your MVC project to use the JsonWebToken class: System.Runtime.Serialization.
You can use the JsonWebToken class to get
a unique and validated user ID like this:
var user = myJWT.Claims.UserId;
If you need to store user specific information then you can use the UserId property to uniquely identify the user making the web service call.
Running the MovieApp
When you first run the Metro MovieApp, you get
a screen which asks whether the app should have permission to use Single Sign-On. This screen never appears again after you give permission once.
Actually, when I first ran the app, I get the following error:
According to the error, the app is blocked because “We detected some suspicious activity with your Online Id account. To help protect you, we’ve temporarily blocked your account.”
This appears to be
a bug in the current preview release of the Live SDK and there is more information about this
bug here:
http://social.msdn.microsoft.com/Forums/en-US/messengerconnect/thread/866c495f-2127-429d-ab07-842ef84f16ae/
If you click continue, and continue running the app, the error message does not appear again.
Summary
The goal of this blog entry was to describe how you can validate Metro apps and Metro users when performing
a call to
a remote web service. First, I explained how you can create
a Metro app which takes advantage of Single Sign-On to authenticate the current user against Live automatically. You learned how to register your Metro app with Live and how to include an authentication token in an Ajax call.
Next, I explained how you can validate the authentication token – retrieved from the request header – in
a web service. I discussed how you can use the JsonWebToken class to validate the authentication token and retrieve the unique user ID.
