Windows Live Delegated APIs

he Internet provides a fantastic backbone for sharing data. For many years Microsoft’s consumer services have helped users manage an assortment of data, such as photos on Spaces and contacts in Messenger and Hotmail. Some of this data you want to share with a set of users; that set can range from the entire user base of the Web to just yourself. An example of data you want to share would be photos of your vacation you put in Spaces for your friends to view. While you might not care if strangers look at your vacation photos, for most other types of data you have an expectation of privacy and security. For example, you wouldn’t want your contacts list to be publicly available. But you would still like to put it online, so that you could access it yourself from multiple locations.

That leads to a problem: The smart way to share data between computers and other people is to place it in an online store, so you and other people can access it, but you want to make sure that only the right people can access it. That’s exactly what the Windows Live delegated authentication system is designed to accomplish. This article explains how to use the Windows Live delegated authentication system to access specific Windows Live data stores.

Users store two distinct types of data online:

  1. Shared data: This is data that users add with a goal of sharing the data with other people. Examples of this on the Windows Live Platform this would be Spaces photos, blog posts, Silverlight streaming media, and Virtual Earth collections.
  2. Private data: This is data users place online so they can access it from other machines but that they don’t want to share. Examples on the Windows Live Platform would be Contacts in Messenger or Hotmail, Favorites, Virtual Earth collections, and calendar.

Some data stored in a Windows Live Service might be considered public, whereas other data stored in the same service could be private. You may have noticed in the list of examples that the Virtual Earth collections are in both the shared and private data sets. That’s because a user might want to share a favorite coastal drive?but not the collection of locations of companies where they’re interviewing for a new job. As a developer building applications on these platforms, your application may potentially have access to data that a user doesn’t want to share, so you need to consider very carefully how your application will work with this data.

You Need My Authority (But You Aren’t Me)
If you are building an application that needs to access a user’s data, your application will need to ask the user to authenticate the access. This authentication can happen in several ways; this article concentrates on Microsoft’s guidelines for such authentication.

The Windows Live delegated authentication technology allows a user to delegate authority to a particular application for a specific set of resources. The user can specify the duration that the application will be able to access the resources; this could be a matter of minutes, days, or months.

Some services provided by Windows Live will offer “open-access” services, services that allow anonymous calls to access the data. Other service offerings will require that the application accessing the data identifies itself in a unique way. It is entirely possible that the same service may provide both anonymous access and identified access. The anonymous access would contain methods to read public-facing data, whereas the identified service method would allow applications to read and write both private and public data.

If the service offered requires that you identify your application with an application identifier, you will need to obtain an application ID (or AppID) from the Windows Live Microsoft Service Manager. The identifier is unique to your application not to you as a developer, or to your company. In other words, you will need a new AppID for each application that you build to access these services.

Windows Live delegated authentication is a technology that allows a user to delegate authority to a particular application for a set of resources.

Once you have an AppID, your application can use this ID to contact the resource provider. The resource providers are the different Windows Live services that support delegated authentication. The number of data sources will expand throughout 2008.

Users Own Their Data
The number one rule is that users always own their data. Your application must never redistribute its copy of a user’s data without consent from that user. This is important. Any application that breaks the user’s trust or the Windows Live terms of usage can have its AppID revoked. Users get to decide the length of time your application can continue to access their data. Within this timeframe your application can request the user data over the wire as often as it is needed.

Permissions Granted
After obtaining an AppID, you need to build a handler page to receive a token known as a consent token. Microsoft sends this consent token to your application after a user consents to allow delegated authentication by your application. A consent token contains four important pieces of information:

  1. A Delegation token: This token allows your application to access the service offered. This token has a short lifespan, usually a matter of hours, but defined by the policy configuration of the target resource provider.
  2. A Refresh token: This is used to get a fresh delegation token when you need to access the service again at a later date. This token will expire when the user whose authority you are delegating decides.
  3. Service Offers (with expiration dates): This is a collection of services to which the user has granted access for your application. An expiration date accompanies each offered service, indicating when your application’s access will expire.
  4. A user identifier: Typically this will be an ID known as the CID.

After building a page to receive this token, you will need to add a link from your application to the Microsoft consent page. When your application makes a call to the consent page, it needs to pass in the address of the return page you built, the address of the privacy policy statement for your site, your AppID, and a list of the services you would like to access. It is good practice to provide users with an explanation before taking them to the consent screen so they can decide whether to grant permission for your application to these services and specify the length of time each service can be accessed.

?
Figure 1. Data Flow in Delegated Authentication: The figure shows the data flow of the delegated authentication process.

Once you have a user’s consent, you can use the delegation token to make server calls from your Web server to the service?typically by passing the delegation token in the HTTP Authentication header of your request. The delegation token will expire in a short time frame, so your application may need to use the refresh token to request a new delegation token. Figure 1 shows the data flow in the delegated authentication process.

If your application knows which user is using it?for example you use the Live ID Web authentication model to manage logged in users?then you probably want to store the consent token associated with the user’s ID. The best approach for this would be to create a new data table in your application’s database to maintain the refresh token and services (with expiration dates) for each user.

Another thing to consider is that the expiration dates you have stored for a user may no longer be valid, because users can change the permissions they have granted to applications at any time. Therefore, you should use the expiration dates only as a guide for your application to determine if you need to present the consent screen to the user again and request a new consent token. If a user has revoked data access permission for your application, your application will receive an unauthorized access response, which it needs to handle gracefully. Your application could reroute the user to the consent screen, indicating why it needs to request permission again.

Editor’s Note: This article was first published in the “Windows Live” edition of CoDe Focus Magazine (2008, Vol. 5, Issue 2), and is reprinted here by permission.

Everything as an Atom
The Atom Publishing Protocol (or AtomPub as it’s often called) defines a simple protocol for performing CRUD (Create, Read, Update, and Delete) operations on data over HTTP. Over the coming months, most of the Windows Live Services will provide offerings that conform to the AtomPub standards. This is a fantastic move toward standardization of the Windows Live Services APIs. In the last few years the APIs emerging from the various Windows Live Services have been varied and numerous. Each product group within Microsoft created their own API set: some were REST based, some were SOAP, and others used WebDav. Standardizing on a single technology to access the Windows Live Services will make developers’ lives easier.

In an ASP.NET server-side development world, much of the code needed to access these AtomPub services can be in a template and reused.

The new AtomPub services will be available for access through the delegated authentication mechanism described in the previous section. Combining these two technologies to create a well-defined mechanism for accessing, authenticating, and working with the Windows Live Services has the following implications:

  • Applications can reuse the authentication code across multiple services.
  • Well-defined architectural patterns can be created to guide application development.
  • Tools will emerge to automate some of the code generation (see the next section).

ADO.NET Data Services (aka Astoria)
At the MIX07 conference in Las Vegas, Microsoft announced a new technology codenamed “Astoria.” Astoria has since been named “ADO.NET Data Services” and is currently available for download as a pre-release (CTP) for Visual Studio 2008 users in the ASP.NET 3.5 Extensions pack.

The ADO.NET Data Services consists of libraries for creating and consuming data services over HTTP. These services can expose CRUD operations invoked through the use of the HTTP verbs (GET, PUT, POST, and DELETE). Does this sound familiar yet?

ADO.NET Data Services are designed to work with standard formats such as JSON and AtomPub. This is really lucky for developers who want to use the new Windows Live AtomPub services!

However, there is more goodness to be harvested from the ADO.NET Data Services, as they provide a mechanism for modeling the data into objects. These objects are instances of entities; you can use the ADO.NET Data Service to represent the data as entities, and also the relationships between the entities, as defined in the service schemas.

If the service offered requires that you identify your application with an application identifier, you will need to obtain an application ID from the Windows Live Microsoft Service Manager.

This means that developers consuming services can interact with Windows Live AtomPub services in terms of .NET objects that they can query, modify, and send back to the service?in other words, they provide a natural way for .NET code to interact with services. Because it is all AtomPub under the covers, openness and interoperability are not compromised.

As a related note, developers wanting to create services that follow the same HTTP interface pattern as Windows Live AtomPub services can use ADO.NET Data Services on the server to easily do that.

Microsoft, Do It for Me
By providing the Windows Live Service offerings in the AtomPub open standard, Microsoft has enabled all developers to access the same services in a uniform way. As an ASP.NET developer, you might not care about those other programmers?but having a well defined and open standard way of accessing the data benefits you as well. In an ASP.NET server-side development world, much of the code needed to access these AtomPub services can be placed in a template and reused.

The ADO.NET Data Services provides this templating technology. An ASP.NET AJAX library abstracts all the nasty details of how to make the HTTP calls, leaving you to focus on how you want to manipulate the data in your application. All you need to do in your ASP.NET AJAX code is create an instance of a Sys.Data.DataService class, passing the URI of the service into the constructor:

   var liveService =       new Sys.Data.DataService(      "xxxxxxx.live.com");

After you obtain a DataService instance, you can perform various operations on the data using the following methods:

  • Query: Retrieve data from the service
  • Insert: Create new data records on the service
  • Update: Change data that already exists
  • Remove: Delete data

Remember that not all services will support all these actions. When an operation fails, it might be because your application doesn’t have the correct authorization, or it could be because the service doesn’t support the attempted operation.

Standardizing on a single technology to access the Windows Live Services will simplify developers’ lives.

Each of these methods creates an instant request over the wire to carry out the operation. You can batch operations together using the createActionSequence method of the DataService object. An ActionSequence is a class that contains a collection of operations to perform on the service. After creating the ActionSequence and adding the operations you want to perform, you call the executeActions method to submit the batched operation requests.

Photos Example
The Windows Live Photos API allows a third party site to request delegated authentication from a user. After the user has granted authentication privileges to a site, the code on that site can make requests to read and write photos associated with that user’s Live ID?the same photos that are displayed on Windows Live Spaces.

The code in Listing 1 provides an example of how to use ADO.NET Data Services to call the Windows Live Photos API. You can see that?by encapsulating the hard work of accessing the service?the code addresses the Windows Live Photos API just as if it were a set of local .NET objects.

The code in Listing 2 shows the details of how to create the supporting classes to provide this extra layer of encapsulation. The LivePhotos class does the heavy listing?and most of that is done by simply deriving from the WebDataContext class.

Writing an article like this before the technology is released presents some challenges, but it can also help you gain insight into how new technologies will impact your work in the near future. As more Windows Live Services start to support the AtomPUB format you (with the help of the ADO.NET Data Services) will be able to access a huge quantity of resources, personal data and relationships between people. All this adds up to a far deeper level of connection between the online applications we build. And still, only the data a user actually wants to expose will be available to web applications. Access will become a new and important consideration for you to handle in your code. How will your application behave if a user denies access to a set of data? Will you provide a downgraded experience? Will you block that user form your site? Will you provide an equally rich experience? As always, a new set of solutions creates its own new set of challenges.

Whatever strategies you decide to adopt in your applications, you can be sure the technologies discussed in this article are starting to open the doors of accessibility to a large number of web developers that have previously found the Windows Live APIs too diverse and complex.

Share the Post:
Share on facebook
Share on twitter
Share on linkedin

Related Posts