Best practices when adding single sign-on to your app with the Live SDK


A few months ago I wrote about how to bring single sign-on and SkyDrive to your Windows 8 apps with the Live SDK. Since then we made the Windows 8 Release Preview publicly available and we’ve begun to see some inconsistency in the design patterns forming in how apps expose entry points for users to sign in, connect accounts or sign-out of their experience.

To help you with these design patterns, we put together some guidelines for apps that want to use a user’s Microsoft account. In this post I share those guidelines with you and show you some code for how to get started.

There are three primary scenarios where your app might need to integrate authentication with Microsoft accounts:

  1. Your app requires the user to be signed in to work.
  2. Your app can work if the user isn’t signed in but provides a personalized experience for users that signed in.
  3. Your app has specific tasks that require Microsoft account sign-in such as integrating with SkyDrive or Hotmail.

Now let’s dive into the details of each of these.

Guidelines for apps that require a user to sign in

If your app uses a Microsoft account as its identity provider and it doesn’t work until after the user signs in, show the Microsoft account sign-in dialog immediately after the app starts. Apps that create or manage info specific to a particular user, such as the People app, fall into this category.

If the user isn’t signed into their PC with a Microsoft account, the app displays a standard sign-in dialog.

Sign-in dialogSign-in dialog.

If the user is already signed into their PC with a Microsoft account, this dialog won’t appear because Windows 8 supports single sign on.

In either case, before your app can get access to the user’s identity they have to grant permission to your app to access their data. This is a one-time process that Windows remembers for subsequent runs of your app across any device and even your website.

Permission dialog
Permission dialog.

To show these dialogs, call the WL.login method (for JavaScript) or the Microsoft.Live.LiveAuthClient.Login method (for managed languages like C#) on app startup.

JavaScript

WL.Event.subscribe("auth.login", onLoginComplete);

WL.init();

WL.login({

scope: ["wl.signin", "wl.skydrive"],

});

C#

public LiveConnectSession Session
{
get
{
return _session;
}
set
{
_session = value;
}
}

private async void InitAuth()
{
if (!Windows.ApplicationModel.DesignMode.DesignModeEnabled)
{
authClient = new LiveAuthClient();
LiveLoginResult authResult = await authClient.LoginAsync(new List<string>() { "wl.signin", "wl.basic", "wl.skydrive" });

if (authResult.Status == LiveConnectSessionStatus.Connected)
{
this.Session = authResult.Session;
}

}
}

For more info about signing in users with the Live SDK, see Signing users in.

Guidelines for apps that work without sign-in but offer a personalized experience for users that signed in

Some apps, for example news or weather apps, may work fine without the user signing into the app but can also offer a personalized experience after the user signs in. For that scenario, we recommend that your app follow the pattern we talk about in this section. Your app must support the Settings charm and provide an Accounts section with a sign-in option. This screenshot shows this pattern used in the People app.

People app showing Accounts section in Settings

People app showing Accounts section in Settings

We recommend the user interaction in which the user clicks the Settings charm, and then clicks Accounts. Then, the Microsoft account sign-in option appears.

To do this, use the SettingsCommand class’s Label property to display this option, and after the user clicks it, use the Invoked property to show a SettingsFlyout control containing the Microsoft account sign-in option. For more info about the SettingsFlyout control, see the “Create settings Flyouts” section in Guidelines for app settings.

Apps that support logging in only with Microsoft accounts can just have a Sign-in option in settings and don’t need an Accounts section because they don’t support multiple accounts. Here is a screenshot of the PhotoBucket app showing a Sign-in option directly in the Settings pane.

photobucket

PhotoBucket app showing Sign In option in Settings

Guidelines for apps that have specific tasks that require Microsoft account sign-in

Certain apps don’t need a Microsoft Account to function but instead provide tasks that integrate with Microsoft Services like Hotmail, SkyDrive and Messenger. An example of which is a custom photo editor app that has a Save to SkyDrive task.

If this is the case for your app, we recommend that you display the Microsoft account sign-in dialog when the user invokes the task that you exposed in your app via the canvas or the app bar. As part of the click event handler, you log in your user and when the user is logged in, perform the task.

Here are some examples that show how to integrate signing in with a Microsoft account and requesting permission to access a user’s SkyDrive account from clicking a button in the App bar.

JavaScript

function onAppBarSaveButtonClick()
{
WL.Event.subscribe("auth.login", onLoginComplete);
WL.init();

WL.login({
scope: ["wl.signin", "wl.skydrive_update"],
});
}

C#

private void AppBarSaveButton_Click(object sender, RoutedEventArgs e)
{
InitAuth();
}

private async void InitAuth()
{
if (!Windows.ApplicationModel.DesignMode.DesignModeEnabled)
{
authClient = new LiveAuthClient();
LiveLoginResult authResult = await authClient.LoginAsync(new List<string>() { "wl.signin", "wl.basic", "wl.skydrive_update" });

if (authResult.Status == LiveConnectSessionStatus.Connected)
{
// An APP level property for the session
App.Session = authResult.Session;
}

}
}

You can customize the appearance of the App Bar button by using one assets provided by Live Connect branding guidelines.

Guidelines for signing out the user

In Windows 8, a user could login in to their PC using their Microsoft account or could have a Microsoft account linked to their local/domain account. In that case, your app doesn’t need to provide a sign-out option. But there will be users who have neither logged in to their PC using their Microsoft account nor linked one to their local/domain account; in this case, if the user is signed into your app with a Microsoft account you need to provide a sign-out option. You can do so by checking if the account can sign out by checking the CanSignOut property of the OnlineIdAuthenticator class.

If your app supports multiple accounts, place signing out in the Accounts section flyout after the user invokes the Settings charm. For apps that support signing in only with Microsoft accounts, put the sign out directly in the Settings here.

photobucket2

If sign out is not permitted, show the name for the logged in user. For more info about the SettingsFlyout control, see the “Create settings Flyouts” section in Guidelines for app settings.

These code samples show how to sign out the user based on our guidelines.

JavaScript

function init()
{
var onlineId = Windows.Security.Authentication.OnlineId.OnlineIdAuthenticator();

If(onlineId.canSignOut)
{
// the sign out button is disabled by default
document.getElementById("btnSignOut").style.visibility = "visible";

}
}

function onLogoutButtonClick()
{
WL.logout();
}

 
C#
LiveAuthClient liveAuthClient;
public SimpleSettingsNarrow()
{
this.InitializeComponent();
liveAuthClient = new LiveAuthClient();

Windows.Security.Authentication.OnlineId.OnlineIdAuthenticator auth = new Windows.Security.Authentication.OnlineId.OnlineIdAuthenticator();

if(auth.CanSignOut)
{
this.btnSignOut.Visibility = Windows.UI.Xaml.Visibility.Visible;
}
}

private void LogoutButton_Click(object sender, RoutedEventArgs e)
{
liveAuthClient.Logout();
}

To sign out a user, call the WL.logout method or the Microsoft.Live.LiveAuthClient.Logout method.

Some rules of thumb

In this blog post, I’ve shown how your apps can take advantage of single sign-on with Microsoft accounts in a way that Windows 8 users expect from Microsoft’s Metro style apps.

I also described the recommended way to provide an option to sign out of your app. In addition to these guidelines, I’d like to end this post with two simple rules of thumb that will prevent you from creating experiences in your app that are inconsistent with the experience users will get from Microsoft’s own apps.

  • Don’t display controls or dialogs to sign in or sign out a user other than those described here. Using the sign-in dialog provided by the Live SDK can help reassure your users that your app can’t directly access their Microsoft account credentials.
  • Don’t display the Microsoft account sign-in or sign out options anywhere other than the SettingsFlyout control or part of a task. Users of Metro style apps have come to expect account management options to be in the Settings charm and doing otherwise will lead to an inconsistent and unexpected experience for your users.

To learn more about the Live SDK you can read our documentation, download the Live SDK, and ask questions on our forums.

–Dare Obasanjo 
   Senior Lead Program Manager, Live Connect Platform

Comments (32)

  1. DBP says:

    It appears that the sign-in widget is a standard Windows 8 feature that doesn't share the credentials with the app, which is of course as it should be. My concern is, what prevents the application from spoofing the standard sign-in feature, making the user think Windows 8 is collecting their credentials when it is actually the app itself? Since apps are full-screen, is there any way to tell the difference?

    My suggestion would be, like many bank password pages these days, to present some kind of information only the user and the OS know on this widget. A malicious app could modify the login screen to simply omit that portion of the display, but this can be overcome via user training. Whatever the result, this seems like a potentially unsafe can of worms to open without some protection against spoofing.

  2. @DBP marketplace certification failure

  3. DBP says:

    @Pizi: Sure, but "Defense in Depth" is a very well-established bedrock of computing security strategy. You should never rely on a single layer of security when you can do more, and Windows 8 seems to fall down on this level. Do you really trust the app certification process to be 100% bulletproof, always? If not, another layer of security would be welcome.

    The sign-on widget isn't even the only instance of this. Pop-up notifications also seem vulnerable to this, and they are potentially harder to catch in an app certification process (because they won't arouse suspicion even if they pop up completely at random; this would cause suspicion in end users if applied to the sign-in widget). Everything is always overlaid on an app's client area, and therefore anything can (in theory) be spoofed– the sign-in widget, notifications, charms, and even app transitions.

    This is why it seems like having the user choose a "safeword" or "safe symbol" as part of OS setup, which could be shown on anything brokered by the OS, is simple common sense. And I haven't seen any indication that anything like it exists.

  4. JW says:

    So, if I want to sign into the application, then eventually I am going to connect to something like a Web Service (let's say WCF) and call a method like GetMyData().  Is there any sample code that demonstrates how the WCF webservice can find out who the user is and grab the userId?  In other words, how can I access the authenticationsession identity bits from within the WCF service so that I can verify that the original user didn't spoof his Id or talk to the web service directly?

  5. @JW,

     See the topic on authenticating a signed in user via Single Sign On. Especially the code sample on GitHub – msdn.microsoft.com/…/hh826544.aspx

  6. AndyCadley says:

    @DBP: One of the big advantages to supporting single-sign on via Microsoft account is that an app never needs to give credentials directly to the app if they login (or associated with their account) with that ID. This helps to increase user confidence in an app as not being something that might steal credentials. For sign-ins to third party services, it's probably preferable for that service's login mechanism to handle any sort of "safe symbol" approach, rather than Windows itself, since then the user has confidence they're dealing with a genuine known service provider rather than a spoof.

    As for pop-ups, I think they mostly follow the good example set by the UAC dialog. Namely that you're granting permission to something via a yes/no question. Sure that can easily be spoofed, but at best a malicious app simply gets a "yes" response, it hasn't actually gained them access to anything new. That makes spoofing system pop-ups a bit of a pointless exercise.

  7. DBP says:

    @AndyCadley, the point is, how do you know that the login UI showing up on the screen when you access the app is the Windows 8 SSO overlay and not a spoofed overlay? That's exactly the point I am trying to make! Apps get every pixel of the screen, and there's no restriction on what they draw there. So no, unless there is something I am missing, there is absolutely no guarantee that the app is "not being something that might steal credentials".

    Think of it this way: This very post has a screenshot of the login UI, right? That isn't the REAL login UI, but just a rasterized bitmap of one (which happens to say ProtoSkyCSharp above it). There's absolutely nothing special about the contents of that screen, and I could mock up a duplicate that most people couldn't distinguish from the real thing, with functional input mechanisms, in no time at all. It doesn't take a single permission to do so. If I show that in an app, how is the user supposed to know whether it's Microsoft's version or mine? But if they "log in" I now have the keys to the kingdom. Now all I would need is data transmission permissions to phone them home.

    THAT is why we need a 'safe symbol' or something similar.

  8. Why only metro style apps having resume functionality, why not windows explorer, word exel powerpoint  and all other

    why don't ms creates metro style apps for all needs

  9. CrystalIce says:

    Are there Native Cpp Samples? Thank you!

  10. Joe White says:

    You say we should use the SettingsFlyout control. Okay, how? It doesn't seem to exist in C#/XAML. The documentation page for SettingsFlyout (msdn.microsoft.com/…/hh701253.aspx) don't have a "C#/XAML" version, and SettingsFlyout is not listed on the "Controls list (Metro style apps using C#/VB/C++ and XAML)" page (msdn.microsoft.com/…/hh465351).

    How are we supposed to follow this guidance, when the control we're supposed to use doesn't exist?

  11. David says:

    I'm also interested in hearing what mitigations are in place for the issues raised by DBP.

  12. hipp0ie2260 says:

    love the 8 hope to see it soon on the mark

  13. hippie2260 says:

    check the truth of it on windows free down load

  14. hippie2260 says:

    wasnt that atrip i see the truth of the 8

  15. behrouz says:

    thank you ..          www.behrouzkiaartgallery.com

  16. JOHN WEEDON says:

    This function is just what windows needed, complementing web mail perfectly and giving the mobile, mobility.

    Looking forward to future developments and maintaining a healthy gap between Microsoft and Apple.

  17. Sam Terry says:

    It's tough, every one has a point and it all makes sense.

  18. aonghas says:

    Why are Microsoft assuming everyone who uses a computer has a PHD in Software Architecture – Design,Sell,Maintain – please don't let the customer be yoor quality controls depatment

  19. Skk says:

    how i develop this type of application like show hide menus and son on ……. this new type of tools available in visual studio 2012???

  20. Patricia Bantom says:

    Check it when i download it, hope it is free!!!

  21. brian says:

    muy buen aporte espero terner ya pronto el windows  8 en mi pc

  22. Rahul says:

    Why only metro style apps having resume functionality

    why not windows explorer, word exel powerpoint  and all other

    why don't ms creates metro style apps for all needs

    Why do always need to go to the left bottom/top corner to go resume the app

    why should we logout before shut down , no immidiate button to shut down

  23. Lorenzo Openito says:

    Just say great job windows 8  think about the world on the at the tip finger

  24. george says:

    windows 8 need to be work on more its not ready yet for use

  25. john hulsker says:

    ben erg tevreden over windows 8

    draait erg goed en nog geen problemen tegen gekomen

  26. charlene faiers says:

    do we sign out an in the same way we do

  27. haard panchal says:

    windows  is phenomenal its fantastic

  28. Erick Miguel says:

    es un nuevo avance en cuanto manejo y funcionamiento de los sistemas operativos

  29. Matias R. Ferreiro Agasi says:

    Hola soy de Argentina, esta página no tiene idioma Español, no me agrada perder tiempo.  No es recomendable!!!

  30. @Joe White

    Here's a link to our Quickstart documentation that walks you through creating a Settings control in XAML: msdn.microsoft.com/…/hh872190.aspx

  31. Cabdulqadir says:

    hi how can I access my account to instull apps to my mobile iPhone to allow browser safari to use download iPhone iPad apps in my mobile

  32. Kirill Bukshuk says:

    Hi, Dare. Thank you for the useful article. Is it possible to connect to SkyDrive within unit tests? I want to test my application's SkyDrive functionality in the unit test library. It seems that the LoginAsync requires a Metro application