How to: Sign In to Windows Live Messenger

The DelegatedAuthControl object was designed to help abstract the functionality that is required to request consent from a user. You can embed the DelegatedAuthControl object on a Web page so that users can initiate the consent and sign-in process for Windows Live™ Messenger.

After the user has granted consent, the application can sign the user in. When the sign-in process is complete, the application can access the user's contacts, create a conversation, and perform other tasks through the User object. This topic describes the code that is needed in order to host DelegatedAuthControl. The coding tasks involved are as follows:

Define an event handler for DelegatedAuthControl.ConsentCompleted event. This event is raised when the user has provided consent for the application to use Delegated Authentication. This event handler should do the following:
- Hide the div element containing DelegatedAuthControl.
- Pass the consent token to the application's server so that it can decrypt consent token and return the user's delegation token.
Define an event handler for the DelegatedAuthIdentity.AuthenticationCompleted event. This event is raised when the user has been authenticated by using the delegation token. The event handler should do the following:
- Instantiate the User object with DelegatedAuthIdentity.
- Subscribe to the User.SignInCompleted event.
- Call the User.SignIn method.
Define an event handler for the User.SignInCompleted event. This event is raised when the user has successfully signed in to Live Messenger. You can use this event handler to perform additional tasks, such as displaying the user's contact list.
Create a server-side function that retrieves the delegation token by decrypting the consent token. On receiving the delegation token from the server, the application should create DelegatedAuthIdentity and subscribe to the DelegatedAuthIdentity.AuthenticationCompleted event.
On loading the host page, the application should do the following:
- Instantiate Microsoft.Live.Messenger.UI.DelegatedAuthControl.
- Subscribe to the DelegatedAuthControl.ConsentCompleted event.

After a user grants consent to an application, DelegatedAuthControl is no longer needed to subsequently sign the user in. Instead, only the following steps are required:

Create DelegatedAuthIdentity with the user's delegation token.
Instantiate the User object with DelegatedAuthIdentity.
Subscribe to the User.SignInCompleted event. This event is raised when a user signs in to Live Messenger.
Call the User.SignIn method.

Note:
The Privacy.htm and Channel.htm pages are required to be present on your Web site domain in order to host DelegatedAuthControl. For more information, see Windows Live Messenger Library Development Basics.

Procedures

Add references to the host Web page

In the <head> element of the page, add a <script> element to load the Windows Live Messenger Library.

<script src="http://www.wlmessenger.net/api/3.5/Loader.js" type="text/javascript" language="javascript"></script>

Within the body of the Web page, add a <script> element referencing your application's main JavaScript file.
```
<script src="SignIn.js" type="text/javascript" language="javascript"></script>
```
Add a DOM element to contain DelegatedAuthControl.

In this example, it is a <div> with the ID "signinframe".
```
<div id="signinframe"> 
        Sign In 
</div> 
```

Add code to your main JavaScript file

Create a new file named SignIn.js and initialize the following variables:
```
_user = null;
_identity = null;
_delAuthControl= null;
```

Create the onScriptsLoaded function to instantiate an instance of DelegatedAuthControl and subscribe to the consentCompleted event.

The application verifier token has to be generated and inserted with server-side code. In the following example, the token should be inserted as a string into the variable appVerifierToken. An application verifier token consists of your application ID and a time stamp, signed with your secret key. For details, see Using Application Verifier Tokens for Delegated Authentication.

function onScriptsLoaded()
{
    var hostUrl = window.location.href;
    var index = hostUrl.lastIndexOf("/");
    hostUrl = hostUrl.substring(0, index);

    var privUrl = hostUrl + "/Privacy.htm";
    var chanUrl = hostUrl + "/Channel.htm";
                
    // Use server side code to set your application verifier token here.
    var appVerifierToken = "appid%3d000000006800FBCC%26ts%3d1235706929%26s";

    _delAuthControl = new Microsoft.Live.Messenger.UI.DelegatedAuthControl("signinframe", privUrl, chanUrl, "en-US", appVerifierToken);
                
    // Replace "logo.jpg" with the URL to your application's logo.
    _delAuthControl.set_applicationLogoUrl("logo.jpg");

    _delAuthControl.add_consentCompleted(consentCompleted);
}

Create the consentCompleted function to define a delegate that handles the consentCompleted event.

At this point, the user has provided consent. However, the user is not authenticated or online. The application must use server-side code to decrypt the delegation token by using the consent token.

function consentCompleted(sender, e) 
{
   var consentToken = e.get_consentToken();
            
   // An application must now pass the consent token to its servers where it can
   // decrypt the token and extract the user's delegation token.
   getDelegationToken(consentToken, onGetDelegationToken);
}

Add the code that will pass the consent token back to the server to retrieve the delegation token. Implement the getDelegationToken function and call the onGetDelegationToken function when the delegation token is returned.
```
function getDelegationToken(consentToken, callback) 
{
   // TODO: send the consent token to the application servers in order to decrypt
   // and return the user's delegation token.
}
```

Create the onGetDelegationToken function to authenticate the user after the delegation token has been retrieved from the server.

function onGetDelegationToken(delegationToken) 
{
   _identity = new DelegatedAuthIdentity(delegationToken);
   _identity.add_authenticationCompleted(onAuthCompleted);
}

Create the onAuthCompleted function to sign the user in to Live Messenger when authentication is complete. This requires instantiating a User object and calling the signIn function.

function onAuthCompleted(sender, e) 
{
   var identity = sender;
           
   if (!e.get_authenticationFailure()) 
   {
      user = new Microsoft.Live.Messenger.User(identity);
      _user.add_signInCompleted(onSignInCompleted);
      _user.signIn();
   }
}

Create the onSignInCompleted function to perform tasks after the user has signed in.

In this example, the current address for the user appears in a paragraph HTML element.

function onSignInCompleted(sender, e) 
{
   if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success) 
   {
       // Display a confirmation message.
       var paragraph = document.createElement('p');
       var confirmMsg = document.createTextNode(_user.get_address().get_address() + ' is now signed in');
       paragraph.appendChild(confirmMsg);

       document.body.appendChild(paragraph);
   }
}

Add the following lines of code to the end of your JavaScript file.

This code will load the appropriate libraries required for DelegatedAuthControl.
```
var loader = Microsoft.Live.Core.Loader;
loader.load(['messenger.core'], onScriptsLoaded);
```

If the user has already provided consent, your application does not need to instantiate DelegatedAuthControl and wait for a consentCompleted event. Instead, if your site has stored the delegation token, you can authenticate the user immediately by creating the User object with the DelegatedAuthIdentity object.

Authenticate with the delegation token

Use server-side code to retrieve user's delegation token that is stored in your application database.
Insert the delegation token into the Web page.

Create the DelegatedAuthIdentity object with the delegation token.

// Use server-side code to insert user's delegation token here.
var delegationToken = " EwCgARAnAAAU7KcbIzqHGnbpm1C2zYa2o9TnbAWAAM1RESuqZ7RK7uZdIzukGspQVPjdnMem";
var delAuthIdentity = new Microsoft.Live.Messeneger.DelegatedAuthIdentity(delegationToken);

_user = new Microsoft.Live.Messenger.User(delAuthIdentity);

Example

The following code example shows the JavaScript required to instantiate DelegatedAuthControl and create delegates to handle the ConsentCompleted and SignInCompleted events.

Code

_user = null;
_identity = null;
_delAuthControl= null;

function onScriptsLoaded()
{
    var hostUrl = window.location.href;
    var index = hostUrl.lastIndexOf("/");
    hostUrl = hostUrl.substring(0, index);

    var privUrl = hostUrl + "/Privacy.htm";
    var chanUrl = hostUrl + "/Channel.htm";
                
    // Use server-side code to set your application verifier token here.
    var appVerifierToken = "appid%3d000000006800FBCC%26ts%3d1235706929%26s";

    _delAuthControl = new Microsoft.Live.Messenger.UI.DelegatedAuthControl("signinframe", privUrl, chanUrl, "en-US", appVerifierToken);
                
    // Replace "logo.jpg" with the URL to your application's logo.
    _delAuthControl.set_applicationLogoUrl("logo.jpg");

    _delAuthControl.add_consentCompleted(consentCompleted);
} 

function consentCompleted(sender, e) 
{
   var consentToken = e.get_consentToken();
            
   // An application must now pass the consent token to its servers where it can.
   // Decrypt the token and extract the user's delegation token.
   getDelegationToken(consentToken, onGetDelegationToken);
}

function getDelegationToken(consentToken, callback) 
{
   // TODO: Send the consent token to the application servers in order to decrypt
   // and return the user's delegation token.
}

function onGetDelegationToken(delegationToken) 
{
   _identity = new DelegatedAuthIdentity(delegationToken);
   _identity.add_authenticationCompleted(onAuthCompleted);
}

function onAuthCompleted(sender, e) 
{
   var identity = sender;
           
   if (!e.get_authenticationFailure()) 
   {
       user = new Microsoft.Live.Messenger.User(identity);
       _user.add_signInCompleted(onSignInCompleted);
       _user.signIn();
   }
}

function onSignInCompleted(sender, e) 
{
   if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success) 
   {
       // Display a confirmation message.
       var paragraph = document.createElement('p');
       var confirmMsg = document.createTextNode(_user.get_address().get_address() + ' is now signed in');
       paragraph.appendChild(confirmMsg);

       document.body.appendChild(paragraph);
   }
}

var loader = Microsoft.Live.Core.Loader;
loader.load(['messenger.core'], onScriptsLoaded);

Concepts

How to: Access Windows Live Messenger Resources
Windows Live Messenger Library Tasks