Windows Live ID Client Authentication
Windows Live ID Client Authentication helps you build personalized, identity-aware, rich client applications for the huge Live ID user base. Client Authentication is a managed API intended for use in developing applications for users' desktops, using .NET Framework. The API lets you:
Rich Client Application Uses for Live ID
- Verify the identity of users of your client application.
- Access information about saved credentials to implement automatic sign in.
- Integrate with other Windows Live services and obtain authentication tickets necessary to access user's personal data provided by them.
- Navigate to Windows Live ID sites in an authenticated browser window.
Wondering what kind of cool functionality Live ID can help you build into your client? Here's an example.
Your rich client application is a word processor for authors. An author uses your application to create documents. By incorporating access to Live Spaces, your application lets the author post their documents to their space and get feedback from their editor and friends.
The Client Authentication Flow
The Client Authentication flow consists of the following:
|Figure 2. Sign-in Dialog for Client Authentication: The figure shows the client authentication sign-in dialog.|
System Requirements for Client Authentication
- A user runs your client application.
- Either automatically or in response to user action, your client calls the Authenticate method. Figure 2 shows the sign-in dialog box that is displayed.
- Users enter their Windows Live ID credentials. If users choose to store their credentials, these are persisted to the local store so they don't need to provide them to your client again in the future—they'll be signed in automatically.
- Your client application sends the user's credentials, encrypted through Secure Sockets Layer (SSL), to the Windows Live ID authentication server.
- The Windows Live ID authentication server validates the credentials and returns an authentication ticket.
- Users are now authenticated, and your client can provide them with personalized features.
- Either automatically, or in response to a user action, your client calls the GetTicket method to obtain a service ticket to access a specific Windows Live ID site or service.
- Your client requests protected content from the Windows Live ID site or service with the service ticket.
- The protected content is returned and displayed to the user.
Your development computer and the user's desktop must be running the following software:
- Windows XP Professional with SP2 or Windows Vista (32-bit versions only)
- IE 6.0 or 7.0/Firefox 1.5 and above
- .NET Framework 2.0
I strongly recommend you use the Visual Studio IDE to develop your client application.
Getting Started with Client Authentication
To start using Windows Live Client Authentication in your rich client application, do the following:
- Get your application ID.
- Install the Windows Live ID Client 1.0 SDK.
- Set up your development environment.
- Implement system requirement detection, authentication, automatic sign in, personalization, and access to Windows Live ID sites and services.
The SDK includes a sample application intended to help you understand how to code your client, by showing you the source code required to implement Windows Live ID Client Authentication features.
Getting Your Application ID
, your unique identifier, is a combination of your organization name, e-mail address, and application name. Declare oIDMgr
as an instance of IdentityManager at the class level so all your code can access it. Pass the application ID as a parameter to the CreateInstance
method and assign the return value to oIDMgr
Setting Up Your Development Environment
oIDMgr = IdentityManager.CreateInstance(
"Windows Live ID Client");
Add a reference to the component to your Visual Studio project, so that you can use Windows Live ID for your client application.
Implementing System Requirement Detection
Clients developed using Windows Live ID for client applications require the Windows Live ID Client Authentication redistributable component to be installed. This component is the assembly (DLL) that contains the Microsoft.WindowsLive.Id.Client namespace. Without this, your client will not run. Your application needs to handle the case when this assembly is not available on the machine.
Call the Authenticate
method to authenticate the user. This method shows the user the sign-in dialog box shown in Figure 2
. This standard dialog box allows the user to enter their Windows Live ID credentials and makes it really easy for you to log the user in. Listing 2
shows you what you need to do when the user clicks the Sign-in/Sign-out button. Declare oID
as an Identity instance at the class level so all your code can access it.
Implementing Automatic Sign-in
Your client must automatically sign-in users who previously signed into your client application and selected the check boxes to remember both their sign-in name and password.
|Your rich client can access Windows Live sites and services through a Web service, an API installed on the local computer or an authenticated browser window.|
To implement automatic sign-in, your application must recognize the concept of this "default user" who will be automatically signed in. Store the sign-in name of this default user in a configuration file, the registry, text file, Web service, or any other method and pass it in as the parameter to the CreateIdentity
Users personalize your client application by specifying various values and settings to customize it. Every time a user signs into your client, you load these values and settings into the application. For example, users could pick a background color for the application or organize their Live contacts in a particular manner.
- Lets the user create data and settings for personalization.
- Stores user-specific data and settings.
- Loads and displays user-specific data and settings when a user logs in.
- Lets users modify or delete their data and settings.
Windows Live ID provides a permanent, unique identifier for the user in the form of the Client ID or CID. Access to the CID is provided through the CID
property of a currently authenticated Identity object. Storing the user-specific data and settings with the CID gives you the power to roam the data across machines. Store the data and settings in a configuration file, the registry, a database, text file, Web service, or any other method of your choice.
Implementing Access to Windows Live ID Sites and Services
Your client can access Windows Live ID sites and services in the following ways:
- Through a Web service API, such as SOAP or XML-RPC.
- Through an authenticated browser window.
For access through a Web service API, your code will:
- Authenticate the user with the Authenticate method.
- Obtain a service-specific ticket with the GetTicket method.
- Add the ticket as a request header for the SOAP or XML-RPC calls.
- For HTTP-based SOAP calls, refer to the documentation for the service to find the URL of the Web Service Description Language (WSDL) file that describes the service and add a Web reference to your application project in Microsoft Visual Studio. Listing 3 demonstrates calling the MetaWeblog API, both to post data and to get data back.
How you open an authenticated browser window depends on which browser the user has installed. For IE 6.0 or 7.0, call the OpenAuthenticatedBrowser
method. For browsers other than IE, invoke the execution of the browser and make sure that the browser sends the appropriate authentication data in a form post to the Windows Live ID site or service URL. Obtain this authentication data by calling the GetNavigationData
|Author's Note: Special thanks to Dave Shevitz and Vivek Nirkhe for their help with this article.