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.
