Guidelines for single sign-on and connected accounts

Applies to Windows and Windows Phone

User authentication scenarios

Users can use their Microsoft account credentials to sign in to devices running Windows 8. When they do this, Windows 8 works with your Windows Store app to enable authenticated experiences for them. These experiences include the following:

  • A user can associate his or her most commonly used operating-system settings with a Microsoft account. These settings are available whenever the user signs in with that account on any device that is running Windows 8 and connected to the cloud. After the user signs in, that device automatically attempts to get the user's settings from the cloud and apply them to the device.
  • Windows Store apps can store user-specific settings so that these settings roam across any devices running Windows 8. As with operating-system settings, these user-specific app settings are available whenever the user signs in with the same Microsoft account on any device that is running Windows 8 and is connected to the cloud. After the user signs in, that device automatically downloads the settings from the cloud and applies them when the app is installed.
  • On Windows 8, a user can associate a Microsoft account with his or her sign-in credentials for any apps or websites, so that these credentials roam across any devices running Windows 8. After the user signs in with that account to a device running Windows 8 and then runs an app or visits a website, if the corresponding stored sign-in credentials are available, Windows 8 attempts to sign the user in automatically.
  • When a user signs in with a Microsoft account to a device running Windows 8, any apps and services running on that device that also use Microsoft accounts for authentication can sign in with that user's Microsoft account and get data that the user has consented to share.

When to use the Microsoft account authentication API

The more you answer "yes" to the following questions, the more you should consider integrating your apps —and your apps' companion websites—with the Microsoft account authentication API.

  • Is your app a Windows Store app?
  • Does your app offer a personalized user experience?
  • Does your app access proprietary cloud services or Microsoft cloud services like Outlook.com and Microsoft OneDrive?
  • Does you app need to provide a user-authentication system, but you don't have the time, knowledge, or infrastructure to create one yourself?

Here are a few categories of apps and companion websites that can benefit from the Microsoft account authentication API:

  • Apps that access proprietary cloud services and that require user authentication. If your app accesses a cloud service and needs to authenticate the user, your code can request an authentication token that allows your app or website to access the cloud service on the user's behalf. The Microsoft account authentication API creates JavaScript Object Notation (JSON)-formatted authentication tokens for the cloud service to use; each authentication token contains a user ID that is specific to your app. To use the Microsoft account authentication APIs to get a JSON-formatted authentication token for use with a proprietary cloud service, see OnlineIdServiceTicketRequest.

  • Apps and companion websites that access Microsoft cloud services like Outlook.com and OneDrive. If your app or its companion website accesses user data in Outlook.com or OneDrive, the Live Connect APIs manage some of the complexities of authentication tokens and make it a bit easier to write code to work with these cloud services.

Adding user-authentication functionality to your Windows Store apps

To code a consistent user sign-in and sign-out experience for your Windows Store apps, see Guidelines for the Microsoft account sign-in experience and Guidelines for login controls.

Caution  

On a Windows 8 device, a user can sign in to that device with a local or domain Windows account that is associated with (or connected to) a Microsoft account. The user can then run a Windows Store app that relies on this particular Microsoft account for sign-in. If the user does so, and if that Windows Store app attempts to sign the user out of the app later by using the guidelines that are described in the topic just mentioned, the user will not be successfully signed out. To prevent this, the app must not show a sign-out command because it won't sign the user out. Instead, the user has a couple of possible ways to sign out of the app:

  • The user can disassociate (or disconnect) his or her Microsoft account from the local or domain Windows account. To do this, in PC settings (shown in the following screen shot), tap Users > Disconnect your Microsoft account > Finish.How to disconnect your Microsoft account
  • The user can switch to using a different account. To do this, on the Start screen, the user taps the account picture, taps Switch account, and then signs in with different account credentials.

If the user follows either of these options, he or she is also automatically signed out of all Windows Store apps that rely on this particular Microsoft account for sign-in.

Putting the user in control

Whenever a user signs in with his or her Microsoft account (or with his or her local or domain Windows account that is connected to a Microsoft account) to a device running Windows 8, the user controls to what extent any app or companion website that uses the Microsoft account authentication APIs can act on his or her behalf. For example, when a user signs in to a participating app that accesses a Microsoft cloud service like Outlook.com or OneDrive, he or she is prompted to give an okay, or consent, to enable that app or its companion website to access the user's associated data or files from those particular cloud services.

However, if the app doesn't want to access data from a Microsoft cloud service like Outlook.com or OneDrive but instead wants to access a proprietary cloud service, typically the user isn't prompted to provide consent unless the user explicitly chose to override this in PC settings > Privacy. However, using the Microsoft account authentication APIs, participating apps and websites can get a user ID that's unique to that app or website. The app or website can then associate data with that user ID. The next time the user signs in, the app or website receives that same user ID and can use it to retrieve any data it has already associated with that user.

On Windows 8, a user can restrict all apps from accessing the name, picture, and other data associated with his or her account without consent. To do this, in PC settings (shown in the following screen shot), the user taps Privacy and then slides Let apps access my name, picture, and other account info to Off. (This option is set to On by default.)

Privacy settings

Responding to user sign-in and sign-out status changes

Apps that use the Microsoft account authentication APIs must respond appropriately whenever a user connects or disconnects his or her Microsoft account from the local or domain Windows account. When a user does this, the ConnectedStateChange background task starts. Whenever this task starts, participating apps must check whether the user's ID for the app has been cleared.

  • If the user's ID for the app has been cleared, the app must first clear any associated tile notifications for that user. If the app indicates whether users have signed in, the app's state should change to show that the user whose ID has been cleared is no longer signed in. However, the app should not reset to its default state. Instead, the app should assume that the user is still using it and is continuing where he or she left off, except in a signed-out state. The only difference is that the signed-out user may no longer have access to cloud services such as tile notifications. Note that this approach will result in different behaviors for different apps. Some apps may need to ask the user to sign in again to continue using them, and others may continue to work but in a signed-out state.

    Note  If the app doesn't store app-specific data to the cloud for the user who has signed out, it's up to the app to decide what to do. We recommend that the app clear all app-specific data for that user from appearing. However, the app should also save this data locally in case the user reconnects his or her Microsoft account to the local or domain Windows account.

  • If the user's ID for the app has not been cleared, it means that the user connected the same account that he or she was already using for the app, and there's nothing further for the app to do here.

For more info about the ConnectedStateChange background task, see the SystemTriggerType enumeration for the OnlineIdConnectedStateChange system event.

For more info about how to check whether a user's ID for an app has been cleared, see the authenticatedSafeCustomerId property.

Code sample

For code that shows how to call the Microsoft account authentication APIs, see the Microsoft account authentication sample.

 

 

Show:
© 2014 Microsoft