Suppose you were the developer of The Volcano Coffee Company's Web site, and you wanted to make it easy for your customers to ship coffee to their friends. One way to do this would be to take advantage of your customers' Windows Live Contacts address books. If this were a one-time shipment to be shipped immediately, you could obtain the user's contacts using the Windows Live Contacts Control. (Visit http://dev.live.com/contactscontrol/v0.2/ for information about the Windows Live Contacts Control.)

On the other hand, if there was a possibility of repeated shipments—let's say your customer buys a one year subscription to the 'Volcano Coffee of the Month Club' for his or her friends—then it would become critical to ensure that the shipping addresses of your customer contacts were up-to-date.

If you need access to information stored by Windows Live services not once, but multiple times, even when the user is not signed in, then Windows Live Data can be the solution.

Before accessing a users' contact data, you must obtain permission from the user to read and/or write the data on his or her behalf. The Windows Live Data system supplies one mechanism by which:

1. Your site can ask for a set of permissions.
   
2. The user can grant or deny the permissions.
   
3. Your site can then utilize the granted permissions to access the data.
   

This article briefly explains how to accomplish these tasks. We assume that the reader is a Web developer who is familiar with HTML and with the HTTP protocol, and can understand C#.

Before your site can successfully obtain permissions using Windows Live Data, it needs to have a valid SSL certificate. For security reasons, Windows Live Data expects to return its permissions using the encrypted HTTPS protocol. If you have a commerce site, you probably already have an SSL certificate so that you can accept credit card information; if not, you'll need to buy a certificate from one of the many certificate authorities and install it on your site.

Note:
If you are just experimenting, you can use Windows Live Data without an SSL certificate using the NoSSL option.

You only need to ask the user for permission once. If the user accepts your permission request, Windows Live Data will provide you with the credentials needed to request access to the user's data.

To ask the user for permission, you will want to add a special 'permission request' link to your Web site page. When the user clicks on the link, Windows Live Data will ask the user to approve or reject your permission request.

The permission link for the alpha release of Windows Live Data will typically be in this form.

<a href="https://ux.cumulus.services.live.com/pgux/default.aspx?rl=[return URL]&pl=[privacy URL]&ps=[permission string]">Grant Permission</a>

Here, the return URL (rl) parameter is the address of the Web page on your site that will process the response; the privacy URL (pl) parameter is the address of a Web page that displays your site's privacy policy; and the permission string (ps) parameter describes the permissions being requested.

So, for example: if your site is www.sample.com; your privacy policy page is privacy.html; your permission processing script is permit.aspx, and you want permission to read the user's Windows Live Contacts information; then you would set your permission link to the following.

<a href="https://ux.cumulus.services.live.com/pgux/default.aspx?rl=https://www.sample.com/permit.aspx&pl=https://www.sample.com/privacy.html&ps=LiveContacts.ReadOnly">Grant Permission</a>

For Windows Live Contacts, the available permissions you can request are:

• LiveContacts.ReadOnly: Read the user's list of contacts and all contact information
  
• LiveContact.ReadWrite: Read, add, update, and delete the user's list of contacts and all contact information
  

If you don't have an SSL certificate for your site and are only testing, then use HTTP rather than HTTPS for your return and privacy URLs, and append the option &NoSSL to your link.

<a href="https://ux.cumulus.services.live.com/pgux/default.aspx?rl=http://www.sample.com/permit.aspx&pl=http://www.sample.com/privacy.html&ps=LiveContacts.ReadOnly&NoSSL">Grant Permission</a>

Note:
The NoSSL option is meant for testing purposes only and should not be used for a live application. If you don't use SSL, Windows Live Data will display a scary warning to the user and advise him or her to reject your request. To bypass the scary warning screen click on the grant permission link on the bottom of the web page.

The response to a permission request will be a form POST to the supplied permission-processing URL that contains several name/value string pairs. The names supplied may include:

• Response Code
  
• DomainAuthenticationToken
  
• OwnerHandle
  
• Permissions
  

The Response Code value may be one of the following:

• RequestApproved: This is the normal response.
  
• RequestRejected: The user denied you permission.
  
• BadPermissionRequestURL: You haven't constructed the request properly. Check your HTML, making sure that the rl field points to a valid HTTPS URL (or a HTTP URL if using NoSSL), and that only the rl, pl, and ps options are included.
  
• UnsupportedPermissions: You have asked for an incorrect permission. Check your HTML, making sure that the ps field is correct.
  
• OwnerWontLogIn: The user did not log into Windows Live, so you don't have permission.
  
• InternalWindowsLiveError: There was a problem at the Windows Live Data server.
  

If the Response Code received is RequestApproved, then the processing page should get the values for OwnerHandle and DomainAuthenticationToken from the posted form. Most sites will want to store the OwnerHandle and DomainAuthenticationToken in a database, keyed to the user's site login credentials. Because these can be used to access personal information, they must be secured properly. A good rule of thumb is to keep the user's OwnerHandle and DomainAuthenticationToken as secure as you would the user's credit card or login information..

If the Response Code is not RequestApproved, then the processing page should take appropriate action. For example, an ASP.NET page written in C# might do this:

protected void Page_Load(object sender, EventArgs e)
{
  string domainAuthToken = null;
  string ownerHandle = null;
  string responseCode = null;

  System.Collections.Specialized.NameValueCollection postedValues = Request.Form;
  for (int i = 0; i < postedValues.AllKeys.Length; i++)
  {
     String nextKey = postedValues.AllKeys[i];
     if ("DomainAuthenticationToken" == nextKey)
        domainAuthToken = postedValues[i];
     else if ("OwnerHandle" == nextKey)
        ownerHandle = postedValues[i];
     else if ("ResponseCode" == nextKey)
        responseCode = postedValues[i];
   }
   if ("RequestApproved" == responseCode)
   {
//OK, get information with ownerHandle and domainAuthToken
   }
   else
   {
//error, display responseCode
   }
}

The Windows Live Data system expects to authenticate the information request in one of three ways:

• Using a Domain Authentication Token returned by Windows Live Data permission system.
  
• Using Mutual SSL Authentication.
  
• Using Relying Party Suite (RPS) Authentication. RPS tokens are used and supplied by Windows Live ID (Passport) by using WS-Trust.
  

Once it has an OwnerHandle and DomainAuthenticationToken, the site will send its information requests to the Windows Live service using an HTTPS request URI. Exactly how that URI will look will depend on the schema of the individual service and the information being requested; in general, for the alpha release, however, it will be in this form.

https://cumulus.services.live.com/[owner handle]/[service]/[data]

For Windows Live Contacts: a GET request will find or obtain information from the service; a POST request will insert information into the service; a PUT request will update information on the service; and a DELETE request will remove data stored on the service. GET requests require Read permission, and the other requests require Write permission.

For example, a request to Windows Live Contacts to retrieve the entire address book for an OwnerHandle with a value of "someone@example.com" might be an HTTPS GET request with an URI of:

https://cumulus.services.live.com/someone@example.com/LiveContacts

There are multiple ways to authenticate this request. One of them requires the site to produce the DomainAuthenticationToken saved earlier and add it to the HTTPS request as a header. This is discussed in Introduction to Windows Live Data Authentication.

The exact format of the response depends on the service and the request. For this particular request, Windows Live Contacts will return an XML document in an XML schema, of which the top level is <LiveContacts>.