Signing users in

Signing in a user with JavaScript

The Live Connect APIs include two methods that you can use to add sign-in functionality to your app with JavaScript: the WL.ui method, which you can use to create a sign-in button; and the WL.login method, which allows you to add sign-in functionality to any HTML element.

You start by initializing the APIs. You can define your own initialization code by using the WL.Event.subscribe method to subscribe to the auth.login event (which is called during sign-in), and then using WL.init to handle the initialization. The API calls WL.init when it loads. Here's how to use WL.init.

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

WL.init({
    client_id: APP_CLIENT_ID,
    redirect_uri: REDIRECT_URL,
    scope: "wl.signin",
    response_type: "token"
});

Note that Metro style apps using JavaScript don't have to specify the client_id, redirect_uri, and response_type parameters in the call to WL.init.

Using WL.ui

After you initialize the APIs, if you want to follow a controls-based approach to signing users in, we recommend that you use the WL.ui method to create a Live Connect sign-in control. With this control, you define the type of UI element you want to create—in this case, a sign-in button.

To add a sign-in control, you need to add a container element, such as a <div> tag, like this.

<div id="signin"></div>

Now you can use WL.ui to create the sign-in control. When this code runs, it adds a sign-in button to the <div> tag that has an ID of signin. After the user clicks the button and successfully signs in, Live Connect asks the user to okay, or consent, to the wl.signin permission level, or scope.

WL.ui({
    name: "signin",
    element: "signin"
});

In general, we recommend that you include the sign-in control as part of your initialization code.

Using WL.login

The APIs support an alternate way to sign in a user with JavaScript: the WL.login method. This method is ideal for situations in which the sign-in control does not meet the needs of your app, or in which the user must provide an additional okay, or consent, for your app to work with the user's info.

Assuming that you initialized the APIs in the previous section, to use WL.login, you provide the specific permission levels, or scopes. Here's how a custom signInUser function calls WL.login to sign in the user with the wl.signin scope. (In this case, the results of the sign in are handled by a custom onLoginComplete function, which is provided later in this topic.) The custom signInUser function is called when the user clicks the accompanying HTML button control.

function signInUser() {
    WL.login({
        scope: "wl.signin"
    }, onLoginComplete);
}

document.write("<button onclick='signInUser()'>" +
    "Sign In</button>");

Handling events

Many of the methods in the APIs support an optional callback parameter that your app can use in JavaScript to control what happens after a call finishes. You can also use an event handler to detect changes in user status. To handle events with the APIs, you use the WL.Event.subscribe method. For example, here's how to use this method to subscribe to the auth.login event, which happens when the user signs in.

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

Another common event to subscribe to is auth.sessionChange. This event happens when some aspect of the sign-in session changes, such as when the user consents to a new scope, like this.

WL.Event.subscribe("auth.sessionChange", onSessionChange);

To handle a session change event, use the WL.getSession method to get a session object for the user. This object contains information such as the user ID, access token, and the scopes to which the user consented. You can use the session object to run code to handle the event.

Here's how to handle the auth.login and auth.onSessionChange events.

function onLoginComplete() {
    var session = WL.getSession();
    if (session.error) {
        document.getElementById("infoLabel").innerText =
            "Error signing in: " + session.error;
    }
    else {
        document.getElementById("infoLabel").innerText =
            "Signed in.";
    }
}

function onSessionChange() {
    var session = WL.getSession();
    if (session) {
    document.getElementById("infoLabel").innerText =
        "Something about the session changed.";
    }
    else {
        document.getElementById("infoLabel").innerText =
            "Signed out or session error.";
    }
}

<UserControl x:Class="CSharpCodeSample.MainPage"
    ...
    xmlns:live="using:Microsoft.Live.Controls">
    <Grid x:Name="LayoutRoot" Background="#FF0C0C0C">
        <live:SignInButton x:Name="btnLogin" Scopes="wl.signin wl.basic" />
        <TextBlock Height="32" Foreground="White" HorizontalAlignment="Left" Margin="8,76,0,0" Name="infoTextBlock" VerticalAlignment="Top" Width="419" />
    </Grid>
</UserControl>

Here's what the XAML code might look like for a Windows Phone app (default page-level attributes are omitted here for brevity; replace CLIENT_ID with your app's client ID and REDIRECT_URL with your app's redirect domain).

<phone:PhoneApplicationPage
    ...
    xmlns:my="clr-namespace:Microsoft.Live.Controls;assembly=Microsoft.Live.Controls">
    <Grid x:Name="LayoutRoot" Background="Transparent">
        <my:SignInButton Name="btnLogin" ClientId="CLIENT_ID" Scopes="wl.signin wl.basic" RedirectUri="REDIRECT_URL" Branding="Windows" TextType="SignIn" SessionChanged="btnLogin_SessionChanged" HorizontalAlignment="Left" VerticalAlignment="Top" />
        <TextBlock Height="32" HorizontalAlignment="Left" Margin="12,78,0,0" Name="infoTextBlock" Text="" VerticalAlignment="Top" Width="419" />
    </Grid>
</phone:PhoneApplicationPage>

Note For Windows Phone apps, you set the SessionChanged event handler method in the XAML code as shown. For Metro style apps using C#, you set the SessionChanged event handler after the call to InitializeComponent, like this.

...
InitializeComponent();
btnSignin.SessionChanged += 
    new EventHandler<LiveConnectSessionChangedEventArgs>(btnSignin_SessionChanged);
...

In the custom method that handles the sign-in control's SessionChanged event handler, do this.

private void btnSignin_SessionChanged(object sender, LiveConnectSessionChangedEventArgs e)
{
    if (e.Status == LiveConnectSessionStatus.Connected)
    {
        session = e.Session;
        client = new LiveConnectClient(session);
        infoTextBlock.Text = "Signed in.";
    }
    else
    {
        infoTextBlock.Text = "Not signed in.";
        client = null;
    }
}

Here's what the code does.

1. Checks to see if the instance of the LiveConnectSessionChangedEventArgs (represented here by the variable e) session exists and is connected successfully.
2. If so, sets the instance of LiveConnectSession (represented here by the global variable session, which was declared earlier) to the connect client's session, so that it can be reused later in code. Also, initializes an instance of the LiveConnectClient class, which represents the connected client's session (represented here by the global variable client, which was declared earlier), so that it also can be reused later in code.
3. If the session can't be established and connected successfully, displays an error message and sets an instance of the LiveConnectClient class to null.

Alternatively, you can prompt a user to sign in without using the Live Connect sign-in control. Or, after an initial sign-in, you can prompt the signed-in user to okay additional scopes that your app needs. One way to do this is to create a button control, and then call this code in the button control's click event handler, like this.

private void moreScopes_Click(object sender, RoutedEventArgs e)
{
    auth = new LiveAuthClient(btnSignin.ClientId, btnSignin.RedirectUri);
    auth.LoginCompleted +=
        new EventHandler<LoginCompletedEventArgs>(MoreScopes_LoginCompleted);
    auth.LoginAsync(new string[] { "wl.signin", "wl.basic" });
}

void MoreScopes_LoginCompleted(object sender, LoginCompletedEventArgs e)
{
    if (e.Status == LiveConnectSessionStatus.Connected)
    {
        session = e.Session;
        client = new LiveConnectClient(session);
        infoTextBlock.Text = "Signed in.";
    }
    else if (e.Error != null)
    {
        infoTextBlock.Text = "Error signing in: " + e.Error.ToString();
    }            
}

GET https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=RESPONSE_TYPE&redirect_uri=REDIRECT_URL

Note

Mobile apps should append &display=touch to the authorize URL.

In this code, replace these:

• Replace CLIENT_ID with your app's client ID.
• Replace SCOPES with the list of scopes to be requested. To specify more than one scope, separate each scope with the escape code for a space, for example, wl.signin%20wl.basic. (For more info about scopes, see Obtaining user consent).
• Replace RESPONSE_TYPE with the specific type of response. If you're using the implicit grant flow, use token to specify an access token to be returned. If you're using the authorization code grant flow, use code to specify an authorization code to be returned.
• If you're using the implicit grant flow, replace REDIRECT_URL with https://oauth.live.com/desktop. If you're using the authorization code grant flow, replace REDIRECT_URL with the URL to your callback webpage. If you specified a redirect domain when you created your client ID (like http://www.contoso.com), the redirect domain portion of the URL must be the same as the one that you specified when your client ID was created. In any case, the URL must use URL escape codes in this REST call, such as %20 for spaces, %3A for colons, and %2F for forward slashes.

  Note For details on the implicit grant flow and the authorization code grant flow, see OAuth 2.0.

When Live Connect receives this call, it checks to see if the user is already signed in. If not, the user is prompted to provide his or her Microsoft account credentials.

After the user successfully signs in and consents to the requested scopes, the Live Connect authorization web service uses the redirect domain to return the user to your app. If you're using the implicit grant flow, you'll see this.

https://oauth.live.com/desktop#access_token=ACCESS_TOKEN&token_type=bearer&authentication_token=
AUTHENTICATION_TOKEN&expires_in=3600&scope=SCOPES

You use this access token (represented here as ACCESS_TOKEN) to work with a user's info. To see how, skip to the end of this section.

However, if you're using the authorization code grant flow, different info is returned, and you'll need to make one more call. Here's what's returned.

http://www.contoso.com/Callback.htm?code=AUTHORIZATION_CODE

If you're using the authorization code grant flow, you use this authorization code (represented here as AUTHORIZATION_CODE) to make another call to obtain an access token.

POST https://oauth.live.com/token

Content-Type: application/x-www.form-urlencoded

client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=
authorization_code

In the body, replace these:

• Replace CLIENT_ID with your app's client ID.
• Replace REDIRECT_URL with the URL to your callback webpage. This URL must be the same as the URL that you specified when you requested an authorization code. The URL must use URL escape codes, such as %20 for spaces, %3A for colons, and %2F for forward slashes.
• Replace CLIENT_SECRET with the client secret that you received when your client ID was created.
• Replace AUTHORIZATION_CODE with the authorization code that was returned on the initial call.

If this second call is successful, the response from the Live Connect authorization web service contains a JavaScript Object Notation (JSON)-formatted object that includes the access token. The access token is contained in a JSON-formatted object that looks like this, where ACCESS_TOKEN represents the actual access token, and SCOPES represents the actual scopes.

{
    "access_token": "ACCESS_TOKEN",
    "expires_in": 3600,
    "scope":"SCOPES",
    "token_type":"bearer"
}

At this point, you can use REST calls to work with the signed-in user's info. For each request, you must append an access_token parameter that contains the access token. Note that the access token is valid for only the number of seconds that are specified in the expires_in value. Here, REST_PATH represents the actual target REST path (like me), and ACCESS_TOKEN represents the actual access token.

https://apis.live.net/v5.0/REST_PATH?access_token=ACCESS_TOKEN