RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Windows Live Delegated APIs

The Windows Live APIs now expose a standard authentication technology that lets your Web application access Windows Live user data easily, yet keeps control in the hands of users.

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.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date