As websites and apps become more personalized, it becomes more important to simplify the authentication process. You can design your app or website to provide a single sign-on experience for your users. For example, if a user is signed into a site that supports Microsoft accounts such as Hotmail or MSN, he or she doesn't have to sign in again to use your website.

Because Windows 8 Release Preview enables users to sign in to their devices by using a Microsoft account, app developers can provide a single sign-on experience across websites and Metro style apps. For example, a website can integrate the Live Connect APIs so that after a user signs in, he or she can also access services that are compatible with Live Connect, like Hotmail and Microsoft SkyDrive. Or, if a user is signed in to a Windows 8 computer, that user will already be signed in to the app's website.

Note  

If you are migrating from the legacy Windows Live ID Web Authentication SDK, you can use the procedures described in this topic to return a uid value from the authentication token.

Enabling single sign-on in your app or website

To enable single sign-on functionality, request the wl.signin scope when the user signs in using Live Connect. For more information on how to sign in the user, see the topic Signing users in. When the user consents to the wl.signin scope, the user is treated as signed in to the app or website when he or she is signed in to any website that supports Microsoft accounts or signed in to a Windows 8 computer using Microsoft accounts.

Authenticating the signed-in user

After the user is signed into your app or website, you may want to validate the user’s identity. This is useful when the user is signed in to a client app and the app wants to retrieve that user's info from your web service. In this case, the web service may want to confirm the identity of the calling user in a cryptographically secure manner.

The key to validating the user’s identity is the authentication token, which contains an app-specific user ID and is encoded as a JavaScript Object Notation (JSON) web token. The basic process for working with the authentication token is:

1. Get the authentication token
2. Decode the token
3. Save the data from each segment of the token
4. Use the user ID value for comparison when a user signs in

Get the authentication token

You can configure an app to obtain an authentication token in one of the following ways. Note that your choice is constrained by the type of app that you are working on.

• The authentication token is one of the values returned after the hash fragment as part of the response to a successful Representational State Transfer (REST) authorization request, as shown here.
  Copy

  http://www.contoso.com/callback.htm#access_token=ACCESS_TOKEN&authentication_token=AUTHENTICATION_TOKEN
  

• In JavaScript, use the authentication_token property of the session object.
• In C#, use the AuthenticationToken property of the LiveConnectSession object.
• In Windows 8, you can use the appropriate classes in the Windows.Security.Authentication namespace.
• In Objective-C, use the accessToken property in the LiveAuthDelegate.authCompleted:session:userState method's session parameter.
• In Java, use the getAccessToken method in the LiveAuthListener.onAuthComplete method's session parameter.

Authentication token format

The authentication token data is encoded as a JSON web token, which is constructed by concatenating an encoded version of the JSON payload with a signed and encoded version of the JSON payload. For more information, see JSON Web Token (JWT). The authentication token can be decoded and verified by using code like the example in the next section. After the authentication token is decoded, the app-specific user ID can be stored and used to identify the user the next time he or she signs in with a valid authentication token.

Authentication token data

The authentication token contains two sets of data: the header that contains metadata about the token, and the body of the token that contains the actual token data. The following table describes the properties of the authentication token.

The following example shows an authentication token and the JSON objects that can be obtained by decoding it.

eyJhbGciOiJIUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiMCJ9.eyJ2ZXIiOjEsICJpc3MiOiJ1cm46d2luZG93czpsaXZlaWQiLCAiZXhwIjoxMzA2Mjk2ODY2LCAiYXVkIjoib2F1dGgudW5pdHRlc3QuY29tIiwgInVpZCI6IjcxNmEyZGY5OWE2MWQ4NzlhMGQ2ZmMyNWM4YzM3MzNmIiwgInVybjp3aW5kb3dzOnBhY2thZ2VzaWQiOiIifQ.gg5I38qJILse6-ELZ3p3cu4qJotcbx6aJ-Cs8TxvM5s

Header: {"alg":"HS256", "typ":"JWT", "kid":"0"}
Token: {"ver":1, "iss":"urn:windows:liveid", "exp":1306296866, "aud":"oauth.unittest.com",
"uid":"716a2df99a61d879a0d6fc25c8c3733f", "urn:microsoft:appurl ":""}

Example helper class code

For an example of how to decode the authentication token into the JSON strings, and how to use the app's client secret to verify that the token has not been tampered with, see the /LiveSDK/Samples/Asp.net/AuthenticationToken/ sample folder in the GitHub - liveservices website.

Build date: 4/26/2012