Core concepts

This topic describes the concepts and guidelines that apply whenever you access a user's Microsoft OneDrive contents from your app.

In this article
Signing users in
Obtaining user consent
User experience
File concepts in OneDrive
Object permissions in OneDrive
Guidelines for apps that interact with OneDrive
Terms

Signing users in

Before your app can work with a user's info, the user must be signed in to their Microsoft account. Typically, you do this is by adding sign-in functionality to your app in the form of a button or a hyperlink. After the user's Microsoft account has been verified, the app receives an access token. This access token confirms that the user successfully signed in and it specifies which parts of the user's info your app can work with and for how long.

The Live SDK support several different ways to help you add sign-in functionality to your app. Windows Store apps use the sign-in features provided by Windows8.1 and other types of apps can use the sign-in UI provided by the service integrated with Microsoft account.

The sign-in process consists of the following steps:

• Initialize the Live SDK

• Allow the user to sign-in to their Microsoft account, if they haven't already signed in

• Get the session info after the user signs in

Design tip:

When you implement the sign-in functionality for your app, we strongly recommend that you use the Live SDK to manage session state. For example, use the Live SDK to determine when to change the sign-in control's text between "sign in" and "sign out", maintain custom user states, and manage access and refresh tokens. If you write custom code to manage session-state logic, that code could cause problems by creating inconsistencies with the session state that is managed by the Live SDK.

To sign users in with single sign-on, see Single sign-on for apps and websites.

Obtaining user consent

Before your app can access a user's data, the signed-in user must consent to letting the app access that data. The service then divides 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

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

• wl.basic Allows access to a user's basic info.

• wl.photos Allows access to a OneDrive user's photos.

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

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.

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.

User experience

The Live SDK 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 Microsoft account authorization web service.

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.

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, your app gets an access token, that lets it 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.

File concepts in OneDrive

Users store a lot of documents and media on OneDrive. Enabling users to access their documents and media from your app can help increase the time they spend using your app and encourage them to share your app with their contacts. Using the Live SDK, you can create, read, update, and delete folders and albums. (An album is a special type of OneDrive folder that's designed to work especially well with photo and video files.) You can upload and download files, read and update file properties, move or copy folders and files, and more.

To upload a file to OneDrive, your code can use HTTP operations such as POST or PUT. You can also use MOVE and COPY to avoid having to download and then upload files that you want to simply move or copy.

When your code uploads a file, and a file with the same name already exists in the same location in OneDrive, the default behavior is for OneDrive to overwrite the existing file. You can add an Overwrite header with a value of false to prevent the existing file from being overwritten. Or you can add an overwrite query-string parameter with a value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose a new name for the uploaded file.

Aside from what's available in the how-to sections about files and folders, you can also do the following:

• Get info about a user's top-level folder in the OneDrive directory. To do this, replace the folder ID with me/skydrive (or USER_ID/skydrive).

• Get info about certain folders by using their friendly names. To do this, use me/skydrive/FRIENDLY_FOLDER_NAME or USER_ID/skydrive/FRIENDLY_FOLDER_NAME, where me represents the current consenting user, USER_ID represents the consenting user's ID, and FRIENDLY_FOLDER_NAME represents an allowed friendly folder name such as my_documents (which represents the Documents folder).

• Get only certain types of items by using the filter parameter in the preceding code and specifying the item type: all (default), photos, videos, audio, folders, or albums. For example, to get only photos, use FOLDER_ID/files?filter=photos.

• Get a limited number of items by using the limit parameter in the preceding code to specify the number of items to get. For example, to get the first two items, use FOLDER_ID/files?limit=2.

• Specify the first item to get by setting the offset parameter in the preceding code to the index of the first item that you want to get. For example, to get two items starting with the third item, use FOLDER_ID/files?limit=2&offset=3.

  Nota

  In the JavaScript Object Notation (JSON)-formatted object that's returned, you can look in the paging object for the previous and next structures, if they apply, to get the offset and limit parameter values of the previous and next entries, if they exist.

• Set the items' sort criteria by using the sort_by parameter in the preceding code to specify the following criteria: updated, name, size, or default. For example, to sort the items by name, use FOLDER_ID/files?sort_by=name.

• Set the items' sort order by using the sort_order parameter in the preceding code to specify the order: ascending or descending. For example, to sort the items in descending order, use FOLDER_ID/files?sort_order=descending.

Object permissions in OneDrive

Users can control who can access certain objects in their OneDrive storage location. This includes objects like folders, files, albums, photos, videos, and audio.

Object permissions in OneDrive are inherited from their parent objects all the way up to a user's top-level folder in the OneDrive directory.

When your code creates or updates an object in OneDrive, your code can't set or change the object's permissions programmatically. Those permissions are inherited automatically. However, an app can allow sharing with a link to grant users read or read/write access to a file or folder. Of course, the user can change an object's permissions through the OneDriveUI.

Your code can't change an object's permissions in a way that would restrict permissions all the way up to a user's top-level folder in the OneDrive directory. For example, if a certain folder allows anyone to access its contents, you can't change the permissions on any of the folder's contained objects to restrict who can access them.

Your code can get a link to a folder or a file, and then you can share that link with other users so that they can access the folder or file directly. We provide several link types, including embedded, read-only, and read-write links, for publicly shared folders and files. These links will work only for users who have permission to view the file.

We also provide preauthenticated links to files; these links work regardless of file permissions. These links should be created only when the user wants to share a folder or file with specific people, because file permissions are not evaluated for these links, and anyone who clicks on the links can view the content.

Guidelines for apps that interact with OneDrive

Apps that interact with OneDrive must conform to these principles:

• Upload files to OneDrive only in response to an explicit user request or choice. Your apps must always ensure that a user intentionally chooses to save any new data to OneDrive. Apps must not upload files to OneDrive automatically without a user making an explicit choice to upload those files.

  Here are some examples of conforming apps:

  • Apps that display an "Upload to OneDrive" or "Share on OneDrive" button that a user must click before each upload of a photo, video, document, or other file.

  • Document-editing apps that require a user to click an "Upload to OneDrive" button initially, so that the app can save that document later without further user interaction.

  Here are some examples of nonconforming apps:

  • Apps that automatically upload to OneDrive any file added to a specific location on a user s devices.

  • Apps that automatically back up files or folders to OneDrive.

  • Apps that display an "Upload to OneDrive" or "Share on OneDrive" button that a user must click before each upload of a photo, video, document, or other file.

  • Document-editing apps that require a user to click an "Upload to OneDrive" button initially, so that the app can save that document later without further user interaction.

  Here are some examples of nonconforming apps:

  • Apps that automatically upload to OneDrive any file added to a specific location on a user s devices.

  • Apps that automatically back up files or folders to OneDrive.

• **Use OneDrive for its intended purpose.**OneDrive includes features both for high-quality document viewing and editing, and for creating and sharing beautiful photo albums. If possible, have your apps take advantage of these features.

• Don't undermine trust in OneDrive. Since OneDrive has been available, users have come to trust it. Preserving that trust is critical, and your apps must not undermine it by doing things that users don t expect, especially with regards to data privacy.

  Here are some examples of conforming apps:

  • Apps that upload documents or photos to OneDrive with user-only access as the default.

  • Apps that warn users that, when the users send a link to their content stored on OneDrive, anyone who receives that link can read the associated files.

  Here's an example of a nonconforming app:

  • An app that makes all shared files in OneDrive publicly accessible by default, without clearly communicating this behavior to users.

Terms

client secret

A unique password that is created when you register your app.

consent page

A UI component that is displayed to users so they can give your app permission to access their info.

package identity

The combination of a unique package name and publisher.

redirect domain

A domain that you assign for your app. The OneDrive service uses this domain to exchange tokens, data, and messages directly with your app, or with your app's companion website.