Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Obtaining user consent

This topic describes how an app requests permission from the user to access data that the user has stored in Outlook.com, Microsoft OneDrive, and other services that are compatible with Live Connect.

Before your app can access a user's data, the signed-in user must consent to letting the app access that data. The Live Connect APIs divide this consent into categories, called scopes.

The common tasks that your app might do to get consent to work with the user's data include:

  • Request the initial scopes for the app
  • Request additional scopes from the user
  • List the scopes to which the app has already been given permission

How to implement these common tasks is described for the languages that the Live Connect APIs support.

To fully understand the code examples in this topic, you can use them in the context of larger code reference samples that we describe in Working with the code examples.

Overview of obtaining user consent

This section describes the basic scopes used to access a user's data and how you can request them from your app.

Common scopes

Some common scopes that your app might want to request are:

  • wl.basic—Allows access to a user's basic info, such as his or her Outlook.com contact list.
  • wl.emails—Allows access to a user's email addresses.
  • wl.photos—Allows access to a OneDrive user's photos.

For a complete list of scopes, see Scopes and permissions.

Requesting scopes

In most cases, you request a user's consent to access his or her info by adding one or more scopes to the sign-in functionality on your site.

Important  

We recommend that you limit the number of scopes you request at any given time to the smallest number necessary to perform a task. This helps your users better understand what they are sharing with your app.

If a user chooses to use a feature that requires a scope that your app doesn't currently have permission to access, your app must get consent for the new scope from the user. The section on Obtaining consent shows how to do that in JavaScript.

User experience

The Live Connect APIs use OAuth 2.0 to enable users to sign in and provide consent to your app. When a user signs in to your app, he or she is redirected to a window that is hosted by the Live Connect authorization web service.

Note  The UI that your users see might differ from these examples depending on your app type and the user's locale.

Windows Live sign-in dialog box

The user types his or her Microsoft account credentials in this window. After signing in successfully, the user is directed to the consent page, which explains what info your app wants to work with.

Important  The data elements for which permission is being requested in this dialog box are determined by the scope values that you set in the call to instantiate the sign-in UI.

Windows Live consent dialog box

If the user clicks Yes, one of these events fires:

  • For JavaScript, the auth.login event fires.
  • For C#, the SessionChanged or LoginCompleted event fires.
  • For Objective-C, the authCompleted or authFailed event fires.
  • For Java, the onAuthComplete or onAuthError event fires.

Your app subscribes to these events so that when one of them fires, the app can obtain the session object from the event-handler method specified by one of the following:

  • For JavaScript, use the WL.Event.subscribe method.
  • For C#, use the SessionChanged or LoginCompleted event handler.
  • For Objective-C, use the authCompleted or authFailed event.
  • For Java, use the onAuthComplete or onAuthError event.

After the user grants permission to access his or her data, your app can begin working with the user's information.

After a user provides consent, Live Connect gives your app a special code, or access token, that lets your app work with the portion of the user's data to which he or she consented. By default, this access token is good for about one hour. After this hour is up, your app won't be able to work with the user's data anymore; it must ask the user to sign in and give consent again. To request permission to access the data for a longer period of time, you can ask the user to consent to the wl.offline_access scope. The wl.offline_access scope gives your app an additional code, called a refresh token, which it can use to get a new access token whenever it needs one—even after the user signs out—and typically for up to a year. However, the user can revoke your app's access at any time. If a user chooses to revoke consent to your app, no corresponding access tokens or refresh tokens will work; your app must ask the user to sign in and give consent again.

Customizing and localizing the sign-in experience

You can customize the consent page— for example, by adding an app logo or providing links to the terms of service and privacy statement for your app. For more info about these settings, see Configuring your app.

You can also display a localized version of the consent page. For JavaScript details, see Signing a user in with JavaScript and HTML for Windows Store apps. For C# details, see Signing a user in with C# for Windows Store apps and Windows Phone apps.

Top

Obtaining user consent in Windows Store apps

Windows Store apps should use the sign-in controls provided by Windows 8. For more info about the Windows 8 sign-in experience, see Guidelines for the Microsoft account sign-in experience.

Obtaining user consent using JavaScript and HTML

This section describes how to obtain user content from a web page an app that uses JavaScript and HTML.

Requesting initial scopes using JavaScript and HTML

If you're using JavaScript with the Live Connect sign-in control, you add a scope property to WL.init and then instantiate the sign-in control by calling WL.ui, as in this example for client-side JavaScript.


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



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


Requesting additional scopes using JavaScript and HTML


function moreScopes_onClick() {
    WL.login({
        scope: ["wl.signin", "wl.basic"]
    }).then(
        function (session) {
            document.getElementById("infoLabel").innerText = "Signed in.";
        },
        function (sessionError) {
            document.getElementById("infoLabel").innerText = 
                "Error signing in: " + sessionError.error_description;
        }
    );
}


Getting a list of current permissions using JavaScript and HTML


function checkPermissions_onClick() {
    WL.login({
        scope: "wl.basic"
    }).then(
        function (response) {
            WL.api({
                path: "me/permissions",
                method: "GET"
            }).then(
                function (response) {
                    var message = "";
                    for (property in response.data[0]) {
                        if (response.data[0].hasOwnProperty(property))
                            message += "<br />" + property;
                    }
                    document.getElementById("infoLabel").innerHTML = result;
                }, 
                function (responseFailed) {
                    document.getElementById("infoLabel").innerText =
                        "Error calling API: " + responseFailed.error.message;
                }
            );
        }, 
        function (responseFailed) {
            document.getElementById("infoLabel").innerText =
                "Error signing in: " + responseFailed.error_description;
        }
    );
}


Top

Obtaining user consent using C# for Windows Store apps and Windows Phone apps

This section describes how to obtain user content from an app that uses C# for Windows Store apps and Windows Phone apps.

Requesting initial scopes using C# for Windows Store apps and Windows Phone apps

If you're using the Live Connect sign-in control in a C# app, you set the initial scopes in the app's Extensible Application Markup Language (XAML) code. To learn how to do this, see Signing a user in with C# for Windows Store apps and Windows Phone apps.

Requesting additional scopes using C# for Windows Store apps and Windows Phone apps


private async void btnMoreScopes_Click(object sender, RoutedEventArgs e)
{
    try
    {
        LiveAuthClient auth = new LiveAuthClient();
        LiveLoginResult loginResult = await auth.LoginAsync(new string[] { "wl.basic" });
        if (loginResult.Status == LiveConnectSessionStatus.Connected)
        {
            this.infoTextBlock.Text = "Signed in.";
        }
    }
    catch (LiveAuthException exception)
    {
        this.infoTextBlock.Text = "Error signing in: " + exception.Message;
    }
}


Getting a list of current permissions using C# for Windows Store apps and Windows Phone apps


private async void btnGetPermissions_Click(object sender, RoutedEventArgs e)
{
    try
    {
        LiveConnectClient liveClient = new LiveConnectClient(this.session);
        LiveOperationResult operationResult = await liveClient.GetAsync("me/permissions");
        this.infoTextBlock.Text = operationResult.RawResult;
    }
    catch (LiveConnectException exception)
    {
        this.infoTextBlock.Text = "Error getting permissions: " + exception.Message;
    }
}


Top

Obtaining user consent using Objective-C for iOS

This section describes how to obtain user content from an app that uses Objective-C for iOS.

Requesting initial scopes using Objective-C for iOS

If you're using Objective-C, you can set the initial scopes in an instance of the login:scopes:delegate:UserState method of the LiveConnectClient interface, like this.


if ([userState isEqual:@"viewDidLoad"])
{
    [self.infoLabel setText:@"Initialized."];
    [self.liveClient login:self 
                    scopes:[NSArray arrayWithObjects:@"wl.signin", nil] 
                  delegate:self 
                 userState:@"signin"];
}


Requesting additional scopes using Objective-C for iOS


- (IBAction)onClickSignInButton:(id)sender {
    if (self.liveClient.session == nil)
    {
        [self.liveClient login:self 
                        scopes:[NSArray arrayWithObjects:@"wl.signin", nil ] 
                      delegate:self 
                     userState:@"signin"];
    }
    else
    {
        [self.liveClient logoutWithDelegate:self 
                                  userState:@"signout"];
    }
}

- (void) authCompleted:(LiveConnectSessionStatus)status 
               session:(LiveConnectSession *)session 
             userState:(id)userState
{   
    [self updateButtons];
    if (session != nil) {
        self.statusLabel.text = @"You are signed in.";
    }
}

- (void) authFailed:(NSError *)error userState:(id)userState
{
    // Failed. 
}

- (void) updateButtons {
    LiveConnectSession *session = self.liveClient.session;
    NSString *signInButtonText = (session == nil)? @"Sign in": @"Sign out";
    [self.signInButton setTitle:signInButtonText 
                       forState:UIControlStateNormal];
}


Getting a list of current permissions using Objective-C for iOS


- (void) displayScopes: (LiveConnectSession *) session
{    
    self.displayLabel.text = [session.scopes componentsJoinedByString:@","];
}


Top

Obtaining user consent using Java for Android

This section describes how to obtain user content from an app that uses Java for Android.

Requesting initial scopes using Java for Android

If you're using Java, you can set the initial scopes in an instance of the login method of the LiveAuthClient class, like this.


Iterable<String> scopes = Arrays.asList("wl.signin", "wl.basic");
this.auth.login(scopes, this);


Requesting additional scopes using Java for Android


public void moreScopes() {        
    auth.login(this, Arrays.asList(new String[] { "wl.basic" }), new LiveAuthListener() {
        public void onAuthComplete(LiveStatus status, LiveConnectSession session, Object userState) {
            if (status == LiveStatus.CONNECTED) {
                resultTextView.setText("Signed in.");
                client = new LiveConnectClient(session);
            } else {
                resultTextView.setText("Not signed in.");
                client = null;
            }
        }
        public void onAuthError(LiveAuthException exception, Object userState) {
            resultTextView.setText("Error signing in: " + exception.getMessage());        
            client = null;
        }
    });            
}


Getting a list of current permissions using Java for Android


public void checkPermissions() {
    auth.login(this, Arrays.asList(new String[] { "wl.basic" }), new LiveAuthListener() {
        public void onAuthComplete(LiveStatus status, LiveConnectSession session, Object userState) {
            if (status == LiveStatus.CONNECTED) {
                resultTextView.setText("Signed in.");
                client = new LiveConnectClient(session);
                String scopes = TextUtils.join(" ", session.getScopes());
                resultTextView.setText("Signed in. Current scopes = " +  scopes );
            } else {
                resultTextView.setText("Not signed in.");
                client = null;
            }
        }
        public void onAuthError(LiveAuthException exception, Object userState) {
            resultTextView.setText("Error signing in: " + exception.getMessage());        
            client = null;
        }
    });
}


Top

Obtaining user consent using REST

This section describes how to obtain user content from an app that uses Java for Android.

Requesting initial scopes in REST

For Representational State Transfer (REST), you specify scopes in the initial call to the Live Connect authorization web service, where CLIENT_ID is the actual client ID, and REDIRECT_URL is either a custom redirect URL or https://login.live.com/oauth20_desktop.srf, depending on your target OAuth grant flow. If you don't specify REDIRECT_URL, the value that was set in the redirect domain is used. For example, if the redirect domain is set to http://www.contoso.com in the app configuration and you don't specify REDIRECT_URL, then consent redirects to http://www.contoso.com#access_token=ACCESS_TOKEN.

https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=wl.signin&response_type=RESPONSE_TYPE&redirect_uri=REDIRECT_URL

Note  

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

You can request multiple scopes at a time. Each scope must be separated by a space, for example: wl.signin wl.basic. For REST, separate each scope with the escape character %20.

To learn more about scopes, see Scopes and permissions, which explains all the scopes that you can use with your app.

Requesting additional scopes in REST

For REST, you must get a new access token that covers the additional scopes and any scopes that were consented to previously. You do this by specifying the list of scopes in a new call to the Live Connect authorization web service, like this.

https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=wl.signin%20wl.basic&response_type=RESPONSE_TYPE&redirect_uri=REDIRECT_URL

Getting a list of current permissions in REST

GET https://apis.live.net/v5.0/me/permissions?access_token=ACCESS_TOKEN

The returned list of permissions will look similar to this. A "1" here represents a scope that the user has already consented to. (If a scope is not listed, the user hasn't consented to it for the app.)

{
    "data": [
        {
            "wl.basic": 1,
            "wl.signin": 1
        }
    ]
}

Top

Next steps

At this point, you understand how to sign users in by using the Live Connect APIs, and how scopes and the consent process work. From here, these topics might be interesting to you:

Top

 

 

Show:
© 2014 Microsoft