Welcome Sign in
Windows Live Developer Center
 Printer Friendly Version      Send     
Click to Rate and Give Feedback
MSDN
MSDN Library
Live Services SDK
Windows Live ID SDK
 Understanding Delegated Authenticat...
Understanding Windows Live Delegated Authentication

February 2008 (Last updated: October 2008)

Windows Live™ Delegated Authentication enables scalable access by Web applications to a user’s personal data and information stored in Windows Live services, but in a structured, user-centered, and constrained manner: explicit user consent is required before that data can be released to or used by other parties.

This white paper explains what Delegated Authentication is and provides a high-level overview of how it can be used by Web application providers.

As the Internet has grown from an interesting academic curiosity into a vital channel for delivering communication and entertainment services, the amount of personal data and information we have stored on various sites for different reasons has also grown. A typical person has a number of e-mail accounts, address books, friends lists, photo albums, and product wish lists on a variety of Web sites.

If a Web site or Web application provides facilities to consolidate or synchronize data between accounts, it usually requires a user to divulge all the credentials for his or her accounts. Such disclosure of credentials gives the Web application an opportunity to impersonate the user and to have access to the user’s data. Unconstrained delegation of account access to a Web application could have unfortunate consequences if the application is either malicious or even just poorly coded.

Always remember the first rule of password and anti-phishing safety: Hand over your password and account credentials ONLY to your identity provider (for example, Windows Live ID), and to NO ONE else.

One of the main reasons why the Windows Live ID system now uses an Extended Validation (EV) Secure Sockets Layer (SSL) certificate (as demonstrated in the following figure) is to help you determine whether you are entering your Windows Live ID sign-in name and password on the correct server, rather than typing it into a spammer’s site.

Cc287613.8b73c49e-8f40-4046-8d5b-ccc786275949(en-us,MSDN.10).jpg

However, the value of allowing software to access our personal data across multiple Web sites can be huge in terms of:

  • Time saved—who wants to keep contact lists up to date manually across a number of different e-mail accounts?
  • Possibilities created by combining data from different sources in new and innovative ways—for example, overlaying your friends’ latest home and work addresses with the details of your travel itinerary for an upcoming business trip could allow unexpected opportunities for reunions with people you haven’t seen for many years.

What we need is a way to enable data-sharing among Web applications, but in a way that gives the user more control of the release of that data and the actions that a site may take with that data.

Delegated Authentication is a new feature offered by Microsoft® that gives Windows Live ID users the ability to consent to the scoped release of their personal information to particular Web sites in a reliable yet flexible manner.

Delegated Authentication is a way to permit access to personal information, but with more precise control over access and usage permissions than the current binary decision—that is, fully on or fully off—that comes with the generally bad practice of handing over your account credentials to another Web site.

Data providers (also known as resource providers) such as the Windows Live Contacts service can register delegation offers that describe the access that a Web application or site (also known as an application provider) can request to a user’s data. The application provider can then request consent from the user by means of the Windows Live consent user interface (the consent UI) to one or more of those resource offers.

Based on the consent decisions the user makes, Windows Live ID gives the application provider a consent token that enables the provider’s Web site to act on the user’s behalf to access the specified services for a period of time defined by the user.

The consent token contains a delegation token, which authorizes a resource provider to provide scoped access to the user’s data in accordance with that user’s consent decisions, even when the user is not signed in. Stated another way, a delegation token enables application providers to act ”on behalf of” Windows Live ID users within the limits of both consent and constrained scope.

Windows Live Delegated Authentication is both a powerful enabler of a new class of user-centered Web services, and also an opportunity for users to take back control of their own personal data and make informed decisions before releasing that data to other parties.

Let’s consider some circumstances under which Windows Live Delegated Authentication can be used.

  • Social networking address book—A social network site can synchronize a user’s Windows Live Contacts list with the user’s “friends” lists from other social networking sites, so the users can keep e-mail and contact information updated as their friends change jobs or move around the country.
  • Sports calendar—A baseball team’s Web site can add appointments to the user’s Hotmail® calendar for all home games.
  • Family photo album—A family Web site service could automatically retrieve the latest digital photographs from each family member’s personal photo-hosting account to create an up-to-date record of family activities.

Of course, the scenarios in which Delegated Authentication can be used are by no means restricted to these areas; the possibilities are many.

Windows Live Delegated Authentication offers a range of benefits to both users and application providers.

For the User

Delegated Authentication enables users to:

  • Maintain control of their personal data and information, and make explicit consent decisions about who they release that data to.
  • Specify, at a granular level, which items of data are released.
  • Grant access to their data for a fixed period of time—whatever they are comfortable with.
  • Review and change their consent decisions at any time.

For Application Providers

Delegated Authentication gives application providers—those whose Web sites invoke actions on behalf of users—the following:

  • A way to access a user’s data from a wide range of Windows Live and Microsoft online services in a constrained way, while abiding by the terms-of-use of those services.
  • A software development kit (SDK) and code samples in seven different programming languages: C# (ASP.NET), Microsoft Visual Basic® .NET (ASP.NET), Java, Perl, PHP, Python, and Ruby. The SDK helps make it easy to support Delegated Authentication.
  • Easy integration with Windows Live ID Web Authentication. The flow of the consent UI is all the smoother if the user has already signed in to Windows Live ID through the application provider’s Web site.

In our discussion so far we’ve already introduced some of the common terms and concepts associated with Delegated Authentication. This section presents a more comprehensive list of those terms. For more information about these and other Delegated Authentication concepts, see the Windows Live ID Delegated Authentication SDK for Application Providers.

Application provider

The host of a Web application that uses Delegated Authentication to communicate with a resource provider and access the resources offered by it.

Consent token

A formatted string that contains the consent information, including the delegation token, refresh token, available offers and actions, and expiration date, returned by the Windows Live ID consent service whenever an application provider requests consent from the user to access a resource provider on the user’s behalf. For details, see Consent Tokens in the Windows Live ID Delegated Authentication SDK documentation.

Delegation token

An encrypted string that represents an opaque ticket. The application provider passes the delegation to the resource provider to authenticate requests for a given resource. For details, see Delegation Tokens in the Windows Live ID Delegated Authentication SDK documentation.

Offer

A resource, registered with Windows Live ID by a resource provider, that can be accessed by an application provider on behalf of a user. For details, see Offers and Actions in the Windows Live ID Delegated Authentication SDK documentation.

Resource provider

A Windows Live service that registers offers and actions with the Windows Live Delegated Authentication system. These offers and actions are the "resources" to which users grant consent for application providers to access. For a list of available resource providers, see the Resource Provider Directory on the Windows Live Dev Web site.

The following figure represents the basic information flow for Windows Live Delegated Authentication as it would apply to the typical usage scenarios described previously.

Cc287613.25c17721-7e87-4d6b-a20d-841f422e0c07(en-us,MSDN.10).jpg

The flow has two phases: the initial steps (the ”granting consent” phase) where the user must be online to grant explicit consent, and the later steps (the “using consent” phase), which can be performed with the user offline if necessary.

  1. “Granting consent” phase—The application provider obtains the user’s consent. (The user must be online.)
    1. The application provider wants to use a Windows Live service (a resource provider) that requires one or more offers. An offer defines the scope of the data to be shared by the resource provider. For more information, see the “Architectural Features” section later in this document.
    2. The application provider sends the user to the Windows Live ID consent user interface (UI) to capture consent for one or more offers.
    3. The user grants or denies consent to the offers requested.
    4. The Windows Live ID service sends a response to a “handler page” on the application provider’s Web site. This response contains an appropriate consent token (which contains a corresponding delegation token, along with some other administrative information) reflecting the user’s consent.
  2. “Using consent” phase—The application provider acts on behalf of the user. (The user can be either online or offline.)
    1. The application provider may have to renew the consent token if the delegation token has expired.
    2. The application provider then calls the resource provider’s application programming interface (API) and includes the delegation token with the call.
    3. The resource provider (a Windows Live service) validates the delegation token and extracts from it the information that identifies the user and offers to which consent has been granted.
    4. The resource provider responds to the application provider’s call by returning the data or performing the action requested.

The first four steps (1.a through 1.d) can be performed only when the user is online because they require the user to interact with the consent UI to grant explicit consent. The final three steps (2.b through 2.d) can be performed either immediately after consent is received (at the end of step 1) or at some later time when the user may not be online.

In all cases, however, the actions that can be performed on the user’s behalf are constrained to the offers and actions to which the user originally consented.

There are several variations to this basic flow. In some cases steps 2.b through 2.d may be repeated at regular intervals, and there are various circumstances under which tokens may have to be refreshed periodically. In general, however, the basic flow just described remains largely the same for all usage scenarios.

As mentioned previously, the user must grant consent before an application provider can use Delegated Authentication to access data. This consent is obtained by means of a delegation-specific user interface (UI) provided by the Windows Live ID consent service. The following figure is an example of this interface, commonly called the “consent UI.”

Cc287613.9a6f2c77-ce83-4161-9f4e-716477a118f9(en-us,MSDN.10).jpg

When consent is required, the application provider directs the user to the consent UI. The UI requires the user to make an informed decision about whether to accept or reject the application provider’s request for access to the specified resources.

The following figure illustrates the basic flow through the consent UI.

Cc287613.6ad2b9e5-d0ae-48a7-aed5-d5e9498aafe6(en-us,MSDN.10).jpg

The following steps occur during the consent UI flow:

  1. An application provider (a Web site or Web application) requests a token for one or more offers from resource providers. This request may trigger the presentation of the consent UI to the user.
  2. The consent UI reads the offer definition.
  3. The consent UI determines whether consent has already been granted. (If consent already exists and is still valid, the flow skips from here to step 7.)
  4. The consent UI presents the requested offer descriptions to the user.
  5. The user grants or denies consent to the given offers.
  6. The consent service records the user’s consent in the consent database.
  7. The consent service responds to the application provider by returning a consent token specific to the offers requested.

After the user has provided consent for access to a resource provider’s offer, the application provider can then interact with that resource provider on the user’s behalf. To do so, the application provider makes one or more calls to an API defined by the resource provider. Because consent has already been granted, the user may not need to be online or signed in when such API calls are made.

Cc287613.471b0a02-867c-4470-8c0b-9ac7473027a9(en-us,MSDN.10).jpg

The following steps occur when the application provider calls the resource provider’s API:

  1. The application provider may request token renewal if the delegation token has expired.
  2. The token renewal service checks for user consent.
  3. A renewed—or “refreshed”—consent token (containing a new delegation token) is returned to the application.
  4. The application provider calls the resource provider’s API, passing the delegation token as evidence of consent.
  5. The resource provider validates the delegation token and rejects access if the token is invalid.
  6. The resource provider retrieves the requested data.
  7. The resource provider responds to the application provider’s API call.

With Windows Live Delegated Authentication, users have control over the consent they grant to application providers. Users can change their minds and revoke permissions to an application provider at any time.

The Windows Live Consent Management page (http://consent.live.com/manageconsent.aspx) enables users to see what permissions they have already granted, and to whom. The following figure is an example of the Consent Management page.

Cc287613.b3f2eef5-3ec2-40f8-8ba0-8b7499088cd5(en-us,MSDN.10).jpg

On this page a user can simply click the Revoke access button to remove permission previously granted to an application provider’s Web application or site.

Windows Live Delegated Authentication is made up of several components, each of which combines with the others to create a robust platform for controlling the release of users’ private data in a constrained, user-centered manner. In this section, we look at each of the key components of the Delegated Authentication architecture.

Offers

Offers are the metadata that drives most of the Windows Live Delegated Authentication system. Note the following key points about offers:

  • An offer definition captures the scope of the data to be shared by the resource provider.
  • An offer is structured into a set of resources, each with a corresponding set of actions that can be performed on that resource. For example, given a resource called “Calendar,” there may be actions defined for “View,” “Update,” and “Sync,” resulting in offers named “Calendar.View”, “Calendar.Update”, and “Calendar.Sync”.

Consent UI

The Delegated Authentication consent UI is the means by which consent decisions are presented to the user by which consent decisions are captured and recorded. The consent UI:

  • Is invoked by the application provider’s Web site to request and capture user consent for an offer or a set of offers.
  • Verifies the identity of the user by requiring him or her to sign in with a Windows Live ID account.
  • Presents the offer details to the user and captures the user’s consent decision—both the granting or denial of access and the time period for which access is being granted.
  • Enables the user to further constrain the consent by choosing the particular details to be shared—for example, granting access to only a certain subset of contacts from an address book.

Consent Token

The consent token is returned to the application provider by the consent UI to represent the user’s consent decision. A consent token:

  • Is typically encrypted and is specific to the application provider that requested the user’s consent.
  • Contains all the other tokens and metadata to enable the application provider to use the consent the user has granted. These components include a delegation token, a refresh token, a list of the offers to which consent has been granted, a location ID for the user’s data, and some token-expiration details.
  • Can be renewed by calling a token-renewal interface with the previously supplied refresh token.

Delegation Token

The delegation token is passed to the resource provider as evidence of the user’s consent. A delegation token:

  • Is returned as part of the consent token that is sent to an application provider, based on the user’s consent.
  • Is an opaque, short-lived token similar to a sign-in cookie. For example, a delegation token may be valid for 12 hours.
  • Can be renewed by renewing the consent token it came from.
  • Is encrypted so that it can be used only by the specific resource provider associated with the offer.
  • Contains an application identifier, a user ID, details about the offers to which consent has been granted, and token-expiration details.

Refresh Token

The refresh token is used to renew an expired delegation token. A refresh token:

  • Is returned as part of the consent token that is sent to an application provider, based on the user’s consent.
  • Is a long-lived token that is valid for the time period matching the user’s consent decision.
  • Is used to renew a consent token and the corresponding delegation token.
  • Is encrypted so that it can be used only by the Windows Live ID token renewal service.

A refreshed consent token (containing a new delegation token) is returned only over a Transport Layer Security / Secure Sockets Layer (TLS/SSL) channel to the requesting application provider’s Web site.

API Call to the Resource Provider

At some point, the application provider that received the consent token makes an API call to the resource provider. The following points are worth noting:

  • The application provider calls the appropriate API associated with an offer—for example, the Windows Live Contacts API.
  • Each resource provider defines the API that it wishes to expose for the data it stores. Resource providers are entirely responsible for defining the offers they provide for each of their resources and the actions that can be performed on those resources.
  • The resource provider specifies how the delegation token is to be included in the API call to it. For Web requests to Windows Live services, though, the delegation token will typically be passed as an HTTP Authorization header.

Token Validation

Before responding to the application provider’s API call, the resource provider must verify that the delegation token is valid and current. The following actions and considerations are important to token validation:

  • A resource provider (such as Windows Live Contacts) uses Windows Live ID library functions to validate the delegation token—for example, to decrypt the token and determine whether it has expired.
  • The library functions extract information from the token for use by the resource provider—for example, the application identifier, the user ID, and details of the offers to which consent has been granted.
  • Validation of the delegation token provides the first line of defense against unauthorized calls. Delegation tokens help resource providers protect themselves against replay and denial-of-service (DoS) attacks from external parties by using proven ticket-validation technology already employed in the Windows Live ID authentication system.
  • After the delegation token has been validated and unpacked, the resource provider can perform additional authorization checks as necessary before processing the API call and returning the requested data to the application provider.

To help application providers get started with Delegated Authentication, Microsoft offers the Windows Live ID Delegated Authentication software development kit (SDK) which you can obtain from the Delegated Authentication download page on Microsoft.com. The SDK includes sample code in seven different programming languages: C# (ASP.NET), Visual Basic .NET (ASP.NET), Java, Perl, PHP, Python, and Ruby.

The SDK and its accompanying documentation contain many more details than can be provided here, but the rest of this section offers a high-level summary of implementing Delegated Authentication from the application provider’s viewpoint.

Registration

To become an application provider, you should register your Web application with Windows Live ID to obtain a unique application identifier token (application ID) and a shared site key for use with Delegated Authentication. You can register your application by using the Azure Services Developer Portal (http://lx.azure.com).

Basic Implementation

Application providers must initiate the consent UI when a user is online in order to request consent for access to his or her data. The Delegated Authentication SDK helps by constructing a special URL hyperlink for your site to send to the Windows Live ID service to begin the consent flow.

Your site must also implement a “handler page” to receive the consent token returned from Windows Live ID for the user. The SDK sample files include some simple examples of handler pages to assist you.

Whether your site should store a consent token on a user’s behalf for use while the user is not online depends on the functionality that your site or application offers and the terms of your privacy policy. Many applications will choose to use the token for a one-time operation performed as soon as the consent is received, and so they won’t need to store the consent token for any length of time.

One thing that your application provider site should not do is to ask for or store a user’s password or other credentials for any resource provider. Delegation tokens completely replace the need for your application to collect users’ account credentials to access a resource provider on their behalf.

The key platform elements required to enable Delegated Authentication services are already available in the Windows Live production environment as part of the Windows Live ID service.

The Windows Live ID Delegated Authentication SDK for Application Providers was released in February 2008, along with the first resource provider to use and support Delegated Authentication: the Windows Live Contacts service.

An increasing number of Windows Live services will be implementing support for Delegated Authentication as resource providers in their next releases; exact timing depends on their release cycles. A current list of resource providers that support Delegated Authentication and links to their documentation is available in the Resource Provider Directory on the Windows Live Dev portal site (http://dev.live.com).

You can start using Windows Live Delegated Authentication now!

  • Download the SDK (see “Resources” at the end of this document)
  • Get your own application ID, try out the SDK samples, and then let your creativity take over as you explore the range of possibilities this technology makes possible while still keeping users in control of their own data.
  • Visit the Windows Live ID Developer Forum to share your discoveries and get answers to your questions.

Windows Live Delegated Authentication is a strategic initiative by Microsoft to enable access to a user’s personal data and information by application providers, but in a structured and constrained manner. Explicit user consent is required before data can be released to or used by other parties. The system is designed for huge scale: it is built on the same well-proven technology as the core Windows Live ID authentication system, which operates at over one billion transactions per day on a global, 24/7 basis.

By using Delegated Authentication, application providers can use the wealth of data and user content available from a variety of Windows Live services to create compelling new applications and data mash-ups for users. But most important, Delegated Authentication is a user-centered system based heavily on the principle that the owner of the data should be in control, and that he or she should decide how and with whom that data is shared.

© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker