Single sign-on for apps and websites

925 out of 1320 rated this helpful - Rate this topic

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.

Because Windows 8 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 Connect APIs so that after a user signs in, he or she can also access Microsoft cloud services that are compatible with Live Connect—services like Outlook.com and Microsoft OneDrive. Or, if a user is signed in to a device running Windows 8, that user will already be signed in to the app's companion website.

Note  

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.

Enable 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.

Top

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.

Top

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 info about how to do that, see Configuring your app, in the "Specify a redirect domain" section.)
    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 the session object's authentication_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. (To specify a redirect domain, see Configuring your app in the "Specify a redirect domain" section for Windows Store apps.) 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.

Top

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.

PropertyNameInfo

Algorithm

alg

The cryptographic algorithm that is used to sign the token. Only HMAC SHA-256 is supported.

Type

typ

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

KID

kid

The key version field of the app.

Version

ver

The version identifier for the token.

Issuer

iss

Identifies the principal that issued the token.

Expiration

exp

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

Audience

aud

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

User Identifier

uid

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

urn:microsoft:appurl

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.

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.

Top

Restrict JWT Issuing option for Windows 8 apps

By default, for a Windows Store app using JavaScript or C#, Live Connect is restricted to issuing authentication tokens 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, Live Connect allows only Contoso Sports to 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, Live Connect allows Contoso News to 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.

Top

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.