Microsoft OneDrive core concepts
This topic describes the concepts and guidelines that apply whenever you access a user's Microsoft OneDrive contents from your app.
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 Windows 8.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
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.
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 and how to use them, 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. See Signing users in with REST.
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 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 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 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.
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
- Get info about certain folders by using their friendly names. To do this, use
me/skydrive/FRIENDLY_FOLDER_NAME or USER_ID
merepresents 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). For more info, see "Using friendly names to access certain OneDrive folders" in Common tasks in accessing OneDrive from your app.
- Get only certain types of items by using the filter parameter in the preceding code and specifying the item type:
albums. For example, to get only photos, use FOLDER_ID
- 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
- 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
- Set the items' sort criteria by using the sort_by parameter in the preceding code to specify the following criteria:
default. For example, to sort the items by name, use FOLDER_ID
- Set the items' sort order by using the sort_order parameter in the preceding code to specify the order:
descending. For example, to sort the items in descending order, use FOLDER_ID
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 OneDrive UI.
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.
OneDrive is the place for a user's content in the cloud. Files in OneDrive should represent content that the user can understand and make decisions about. OneDrive is not the place to store app state data, such as settings and configuration for your app. OneDrive is the place to store documents, photos, videos, music, and other content that was created or edited by the user.
Upload files to OneDrive only in response to an explicit user request or choice
Apps should generally only upload files to OneDrive in response to an explicit user request or choice. Users should know and understand that their data will be saved in OneDrive.
Here are some examples of good uses of OneDrive:
- Apps that ask the user if they want to store all files on OneDrive as part of a first run experience.
- Apps that display a Save to OneDrive or Share on OneDrive button that a user clicks before uploading a 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 bad uses of OneDrive:
- Apps that create an application settings file in the root of a user's OneDrive to roam settings between different devices.
- Apps that upload files the user explicitly saved to a location that the user expects to only keep the file on the device.
Use OneDrive for its intended purpose
Building your app in alignment with the intended purposes of OneDrive ensures that your application respects the user's data in OneDrive and provides a great experience both inside your app and when using the OneDrive experiences.
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. For example, apps should never make all shared files in OneDrive publicly accessible by default, without clearly communicating this behavior to users.
An authorization code that is requested by the client, to be authenticated by the server and gain access to user info.
A unique password that is created when you register your app.
A UI component that is displayed to users so they can give your app permission to access their info.
The combination of a unique package name and publisher.
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.
A replacement access token to interact directly with the Live SDK REST API.