ID Login Control Reference

IDLogin Control Reference


The IDLogin control quickly allows you to provision a Windows Live ID authentication for your application. You simply drag and drop the control on your Web page, provision your Application ID, and compile/run the project. This also provides for client/server-side events for sign-in/sign-out user actions, a property to maintain your application context, and properties to specify background/foreground colors to mesh with your Web page.

When you drag and drop IDLogin control from the toolbox to your web page in designer view, IDLogin control adds wll_appid and wll_secret keys to the <appSettings> section of your project's web.config file. These keys hold the values for your Application ID and Secret that you can create from http://msm.live.com/app

You can create Application ID directly from the IDLogin control. When you view the IDLogin control on your web page in designer view, you can invoke the "Create a new Application ID" action. This action navigates you to http://msm.live.com/app. After you create an Application ID and close the form, the Application ID and Secret is saved to the <appSettings> section in the keys wll_appid and wll_secret.

The following example shows how to declare an IDLogin control in an ASP.NET page and set properties to provide configuration settings keys for Application ID and Secret. 

<live:IDLogin ID="IDLogin1" runat="server" ApplicationIDConfigKey="wll_appid" 
      ApplicationSecretConfigKey="wll_secret" />

IDLogin Control Properties

Property

Description

ApplicationContext

Optional

The context parameter serves to hold state for your application. For example, if the user at www.example.com/contactus.aspx, you can pass contactus.aspx as context and when the user is redirected back to www.example.com, you can send them back to contactus.aspx to continue their flow. The Windows Live ID service will convert unsafe characters to safe characters, and may discard the value that you provide here. We recommend that you handle state in your application by using your own proprietary cookies.

Style

Optional

Used to make the sign-in IFRAME visually fit with your site. The supported style parameters are: font-family, font-weight, font-style, font-size, color, and background.

 

These parameters are defined according to CSS specifications. When you specify a value for the style parameter, you must supply the style parameters in a semi colon-delimited, URL encoded form.

For example, the following shows an unencoded style string: font-size: 12pt; background: lightgreen; font-weight: bold;

The following shows what the string resembles after URL encoding: font-size%3A%2012pt%3B%20background%3A%20lightgreen%3B%20font-weight%3A%20bold%3B

Action

Read Only

The action that the user is doing. The list of possible values:

  • login: The user completed a successful sign in to your site.
  • logout: The user completed a successful sign out from Windows Live. You should clear the user’s cookies and display the default, signed out page.
  • clearcookie: The Windows Live ID Sign Out page is calling your site to clear user cookies.

ApplicationUserID

ReadOnly

UTF-8 encoded alphanumeric string that represents the unique user identifier. This identifier is unique to this user, and specific to your site.

ApplicationIDConfigKey

Required

Name of the <appSettings> key that contains the value of the Application ID for your application. Default value set by the control is wll_appid.

ApplicationSecretConfigKey

Required

Name of the <appSettings> key that contains the value of the Application Secret for your application. Default value set by the control is wll_secret.

TimeStamp

ReadOnly

A 32-bit integer that represents the time that the user last authenticated in seconds as measured from Jan 1, 1970 GMT.

IDLogin Events

Event

Description

OnClientSignIn

A client- side event handler that gets called when user signs in.

Event handler signature (in JavaScript):

   function (sender, args)

where

  • sender is the DOM element raising the event.
  • args is the event arguments and has methods get_cancel() and set_cancel()

 

You can use the set_cancel method to cancel the execution of a server event associated with a user sign in action.

The following example shows the declaration of the IDLogin control and the OnClientSignIn event handler which executes when a user signs in and cancels the server signin event: 

<live:IDLogin ID="IDLogin1" runat="server"
ApplicationIDConfigKey="wll_appid"
ApplicationSecretConfigKey="wll_secret"
OnClientSignIn="OnClientSignIn"/>
function OnClientSignIn(sender, args){
//add client side signin event logic here
args.set_cancel(true); //cancels the server event
}

OnClientSignOut

A client-side event handler called when a user signs out.

Event handler Signature (in JavaScript): 

   function (sender, args)

where

  • sender is the DOM element raising the event.
  • args is the event arguments and has methods get_cancel() and set_cancel().

Use the set_cancel method to cancel the execution of a server event associated with a user sign out action.

OnServerSignIn

A server side event handler that gets called when user signs in.

Event handler signature (in C#): protected void (object sender, AuthEventArgs e) 

  
where 
  
      
  • >sender is the IDLogin object.   
  • e is the Event Arguments 
  
The AuthEventArgs class is derived from the EventArgs class and has the following members which are accessible during server- side event handling: 
  
      
  • Action   
  • ApplicationContext   
  • ApplicationUserID   
  • TimeStamp
  
    
OnServerSignOut
    
A server-side event handler tcalled when a user signs out 
  
Event handler signature (in C#): 
protected void (object sender, AuthEventArgs e) 
  
where 
  
      
  • sender is the IDLogin object.   
  • e is the Event Arguments.