Single sign-on for apps and websites

This topic describes how to use the single sign-on feature for apps and websites.

In this article
Enable single sign-on in your app or website
Authenticate the signed-in user
Get the authentication token
Get authentication token data
Restrict JWT Issuing option for Windows Store apps

As apps and websites 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 an app that supports Microsoft accounts, he or she doesn't have to sign in again to use a companion website.

Enable single sign-on in your app or website

Because Microsoft Windows enables users to sign in to their devices by using a Microsoft account, app developers can provide a single sign-on experience across Windows Store apps and companion websites. For example, a website can integrate the Live SDK APIs so that after a user signs in, he or she can also access Microsoft cloud services. Or, if a user is signed in to a device running Windows 8 or Windows 8.1, that user will already be signed in to the app's companion website.


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

To enable single sign-on functionality, request the wl.signin scope when the user signs in using a Microsoft account. 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 WindowsRT8.1 computer using Microsoft accounts.

Authenticate 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 a companion web service. In this case, the web service may want to confirm the identity of the user in a cryptographically secure manner.

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

  1. After the user successfully signs in and consents, the app or website gets the authentication token and saves it to a location that's recognized by the companion web service for example, in a secure database.

  2. The companion web service gets the saved authentication token, verifies the authentication token's signature by using the app's or website's client secret, and then decodes the authentication token to get the authentication token data.

  3. The companion web service gets the user identifier value and optionally also the package SID value or the audience value, or both from the authentication token data. The companion web service then compares these values to any values that it's able to get for the user independently. If the values match, the user's identity is confirmed. Then, for example, the companion web service could call the previously mentioned secure database along with the matching values to get any settings that were previously stored for the user settings such as the user's high game scores, subscription details, or shopping-cart status. How the companion web service does all of this is up to the developer and is outside the scope of this topic.

Get the authentication token

To get the authentication token, use one of the following API calls.

  • For Representational State Transfer (REST), the authentication token is one of the values returned after the hash fragment as part of the response to a successful REST authorization request. It is represented in the following example as AUTHENTICATION_TOKEN. Note that you must first specify a redirect domain for your app.

    For more info, see Server-side scenarios.

  • For web apps using JavaScript, use thesession object'sauthentication_token property. You can get the session object by calling the methods WL.Event.subscribe, WL.getLoginStatus, WL.getSession, and WL.login.

  • For Windows Phone apps using C#, use the Microsoft.Live.LiveConnectSession object's AuthenticationToken property.

  • For Windows Store apps using JavaScript or C#, you must first specify a redirect domain for your app. After you specify a redirect domain, use the session object's authentication_token property (for JavaScript) or the Microsoft.Live.LiveConnectSession object's AuthenticationToken property (for C#).

  • For iOS apps, use the LiveAuthDelegate.authCompleted:session:userState method's session parameter's authenticationToken property.

  • For Android apps, use the LiveAuthListener.onAuthComplete method's session parameter's getAuthenticationToken method.

Get 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 cryptographic algorithm that is used to sign the token. Only HMAC SHA-256 is supported.



The type of token. Only a JSON web token is supported.



The key version field of the app.



The version identifier for the token.



Identifies the principal that issued the token.



Identifies the exact time when the token expires. This time is expressed in the number of seconds since 1 January 1970.



Identifies the audience for which the JSON web token is intended. In this case, it is the domain name for the app.

User Identifier


An identifier for the user, which is unique to the app. This is equivalent to the pairwise ID from the legacy Windows Live ID Web Authentication SDK.

Package SID


The Windows client identifier for the app, if there is one.

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


Header: {"alg":"HS256", "typ":"JWT", "kid":"0"}
Token: {"ver":1, "iss":"urn:windows:liveid", "exp":1306296866, "aud":"",

To verify the authentication token's signature by using the app's or website's client secret, and to decode the authentication token, use code similar to that in the GitHub - liveservices website's /LiveSDK/Samples/ sample folder.

Restrict JWT Issuing option for Windows Store apps

By default, for a Windows Store app using JavaScript or C#, authentication tokens are issued for that app only. This behavior is designed to prevent other Windows Store apps from getting authentication tokens that use the originating app's info. This behavior is specified in the Live Connect app management site for the originating app, in the API Settings page's Restrict JWT Issuing option, which is set to Yes by default.

To override this behavior, allowing other apps to get authentication tokens that use the originating app's info, set the Restrict JWT Issuing option to No.

For example, consider two apps that both use the same back-end web service: Contoso Sports and Contoso News. If Restrict JWT Issuing is set to Yes (the default) for Contoso Sports, only Contoso Sports will get authentication tokens for its users; Contoso News can't get authentication tokens for users of Contoso Sports. However, if Restrict JWT Issuing is set to No, the Contoso News will get authentication tokens for users of Contoso Sports. This can be accomplished by having the back-end web services for Contoso News and Contoso Sports share user settings. However, the back-end web service won't also be able to easily distinguish, if it needs to, between authentication tokens coming from Contoso News and those coming from Contoso Sports.