Before your client app can start using Extensible Messaging and Presence Protocol (XMPP) to sign in to the Windows Live Messenger XMPP service and interact with a Messenger user and his or her buddies, there are several things you must do.
Prerequisites
Before you prepare to sign in your app to the Messenger XMPP service, you need to know this:
- Live Connect doesn't provide any XMPP libraries. If you don't have a preferred XMPP library to use, you may want to explore the list of available XMPP libraries at XMPP Standards Foundation - Libraries. You will have to write some code to get any of these libraries to work with the Messenger XMPP service. For details, continue reading this topic.
- For the XMPP extensions and features that we support, see Messenger XMPP reference. Your app must support XMPP: Core functionality and, optionally, may implement the XMPP extensions we support.
Prepare to sign in
Before your app can sign in to the Messenger XMPP service, you need this info:
- To connect to the Messenger XMPP service, either use Domain Name System (DNS) SRV records for messenger.live.com or connect directly to xmpp.messenger.live.com on port 5222.
- Secure Sockets Layer (SSL) is required.
- Your app must implement see-other-host. For details, see the "see-other-host" section in RFC6120: XMPP: Core.
Note The see-other-host requirement is a breaking change beginning with the April 2012 release. All apps, including those that work with the December 2011 release, must implement see-other-host. Any app that implements Messenger XMPP but doesn't also implement see-other-host will no longer work.
- We use X-MESSENGER-OAUTH2 Simple Authentication and Security Layer (SASL) authentication to get a user's okay, or consent, for your app to represent the user when signing in to the Messenger XMPP service. To do this, we use the OAuth 2.0 standard. To use our implementation, your app needs a client ID and an access token (and possibly other info, depending on your app type). To get these, see the Get a client ID and Get an access token sections later in this topic.
Get a client ID
Before your app can sign in to the Messenger XMPP service, you need a client ID. A client ID is a unique code that identifies your app to the Live Connect authentication service and is exchanged for an access token, which is explained in the next section. To get a client ID (and, depending on your app type, to get a client secret and specify a redirect domain), follow the instructions in Configuring your app.
Get an access token
After you have a client ID (and other info, depending on your app type), your app needs to give this info to the Live Connect authentication service in exchange for an access token. This access token allows your app to sign in to the Messenger XMPP service for a specific user who has okayed, or consented, for your app to act on his or her behalf. (To get a client ID, see the Get a client ID section earlier in this topic.)
To get an access token, you need to use the client ID and specify a user consent level, which we call a scope. The specific scope that you need to use here is wl.messenger.
To use the wl.messenger scope and your client ID to get an access token, follow the guidance and code examples in Signing users in and Obtaining user consent. For additional guidance and more complete code samples, go to the following information and resources depending on your app type:
- Windows Store apps: See the JavaScript and C# code in Windows Store apps and Working with the code examples. To get the access token, for JavaScript, you can call the WL.getSession method and look in the returned access_token property for the session object. For C#, in the custom event handler method that you specify for the LiveAuthClient.LoginCompleted event, look in the LoginCompletedEventArgs.Session.AccessToken property.
- Windows Phone app: See the C# code in Windows Phone apps and Working with the code examples. To get the access token, look in the LoginCompletedEventArgs.Session.AccessToken property in the custom event handler method that you specify for the LiveAuthClient.LoginCompleted event.
- iOS apps: See the Objective-C code in iOS apps and Working with the code examples. To get the access token, in the LiveAuthDelegate.authCompleted:session:userState method, call the session parameter's accessToken property.
- Android apps: See the Java code in Android apps and Working with the code examples. To get the access token, in the LiveAuthListener.onAuthComplete method, call the session parameter's getAccessToken method.
- Client-side website or script that uses JavaScript: See the code in Web apps. To get the access token, you can call the WL.getSession method and look in the returned access_token property for the session object.
- All other app types: See the Representational State Transfer (REST) code in the "Signing a user in with REST" section in Signing users in to learn how to get the access token.
Sign in
After you have an access token, your app can sign in to the Messenger XMPP service on behalf of the consenting user. (To get an access token, see the Get an access token section earlier in this topic.)
As stated in the previous section, the Messenger XMPP service uses X-MESSENGER-OAUTH2 SASL authentication. Your app sends the access token as the SASL token for authentication, as shown in the following partial exchange of protocol info, where ACCESS_TOKEN represents your access token.
... < <stream:features xmlns:stream="http://etherx.jabber.org/streams"><mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"><mechanism>X-MESSENGER-OAUTH2 </mechanism></mechanisms></stream:features> > <auth xmlns="urn:ietf:params:xml:ns:xmpp-sasl" mechanism="X-MESSENGER-OAUTH2">ACCESS_TOKEN</auth> < <success xmlns="urn:ietf:params:xml:ns:xmpp-sasl" /> ...
Remember that your code must first connect to the Messenger XMPP service by using DNS SRV records for messenger.live.com or by connecting directly to xmpp.messenger.live.com on port 5222.
Note The Messenger XMPP service uses the user ID in the access token to sign the user in and to bind the user to the session. To do this, Jabber IDs that are assigned by the Messenger XMPP service use the format identifier@messenger.live.com instead of a Microsoft account user ID.
Next steps
Now that you've learned the basics, you can use our XMPP code examples.
Build date: 4/16/2013
