Introduction to OAuth

This topic provides a brief introduction to the concepts and relationships that make up OAuth 2.

Last modified: March 28, 2015

Applies to: OneNote service

Like many web technologies, OAuth 2 is wondrously confusing when you're just starting out. Most of that complexity comes from its flexibility, so for individual cases like a Windows Phone app, things are usually much simpler. We're not going to explain all there is to know about OAuth here, but instead point you in the right direction for using it with the OneNote API. We'll lay out the landscape, and help you navigate through it to the places you'll most quickly get what you need.

The first thing to know is that there are three players working together to make OAuth function. Each of the players are computer systems of one form or another (humans just prove they really are who they say they are, and say "yes" or "no" to agree to what's happening). The three players are:

  • The resource server: That's typically the computer server or service that holds the user's information, and ensures that only authorized clients can access it. When you write apps that use the OneNote API, the resource server is the OneNote, though technically it passes the tokens on to Microsoft OneDrive for access.

  • The user agent, also known as the client: That's the application, or maybe a website, that is trying to access the data because the user told it to.

  • The authorization service: That's the system that knows how to securely log in the user, how to ask for their permission, and how to securely create a token that tells the resource server that the user agent is legitimately authorized. For OneDrive and the OneNote API, the authorization service is Microsoft Live.

The over-simplified flow is that the user starts up an app (a user agent), and uses it to try and access their data (stored on the resource server). The app gets the user's name and password, and sends those to the authorization service. The app also sends identification information about itself, and what kind of access it's asking for. The app identification information, known as the client ID, is created ahead of time by the app developer (that's you). The scope indicates what kind of access the app is asking for. The authorization service makes sure the user is who they say they are, and that they agree to allow the kind of access that the app is requesting. Then, using one of a couple different flows, the authorization service ultimately returns some form of token to the user agent. Assuming the process goes smoothly, the user agent can then access the user's data (located on the resource server) for a certain amount of time, after which the token expires, and is useless. In some flows the app can refresh the token, and in other cases they have to do the whole sequence again.

So, if it's that simple, why is it so confusing?

Well, at each of those "A asks B for C" steps in the sequence above, there are a variety of optional flows, and ways of doing what needs to be done. If you've tried reading the OAuth specs, those cover not only both sides of the handshake, (specifying the behavior of both A and B), but also the many variations, permutations and combinations of who does what to whom. Like most modern systems designed to work everywhere, it can get very complicated.

Each app that needs access to your information has to tell the OAuth authorization service exactly what it wants to do. The range of available actions can include things like accessing your contacts, location, and so on. You've likely seen what happens when an app requests access on your phone or computer. The API is no different in that respect. A named scope is a string that's understood by the authorization service as referring to a specific set of access rights. There are four defined scopes for the API, allowing the app to have read or write access to all notebooks in the user's OneDrive. If your app needs to use refresh tokens, we recommend that you also include the wl.signin and wl.offline_access scopes.

After you have that refresh-able token, your app should keep track of when it was issued, and its expiry time. If the token has expired, it's considered good practice to go ahead and request a new token before your app makes its next request. Submitting a token without calculating whether it's already expired will return an error to your app, and is generally considered impolite.

To learn more about Live scopes, visit the Scopes and permissions page on MSDN.

For more in-depth information visit Configuring your app in the Live Connect Developer Center documentation.