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.

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.

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

  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 following example shows an authentication token and the JSON objects that can be obtained by decoding it.

eyJhbGciOiJIUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiMCJ9.
eyJ2ZXIiOjEsICJpc3MiOiJ1cm46d2luZG93czpsaXZlaWQiLCAiZ
XhwIjoxMzA2Mjk2ODY2LCAiYXVkIjoib2F1dGgudW5pdHRlc3QuY2
9tIiwgInVpZCI6IjcxNmEyZGY5OWE2MWQ4NzlhMGQ2ZmMyNWM4YzM
3MzNmIiwgInVybjp3aW5kb3dzOnBhY2thZ2VzaWQiOiIifQ.gg5I3
8qJILse6-ELZ3p3cu4qJotcbx6aJ-Cs8TxvM5s

Header: {"alg":"HS256", "typ":"JWT", "kid":"0"}
Token: {"ver":1, "iss":"urn:windows:liveid", "exp":1306296866, "aud":"http://www.contoso.org",
"uid":"716a2df99a61d879a0d6fc25c8c3733f", 
"urn:microsoft:appurl":"ms-app://s-1-15-2-355948911-3179402394-1368051653-2073632810-3145016855-291163204A-157622137B"}

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/Asp.net/AuthenticationToken/ 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.