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