Authenticating with the OneNote APIs
Hello world! Dipak Boyed, member of the OneNote API team here. Today, I'd like to provide a few pointers on how authentication works with the OneNote APIs. Specifically, going over some of the gotchas that our launch partners encountered and list out useful links and references.
While developing the APIs, it was clear to us early on that the biggest hurdle for developers trying to code against our APIs was going to be Auth. We wanted to provide a simple auth story that built on top of Microsoft Account (MSA) given the API needed to interact with a user's notebook in OneDrive and OneDrive needs MSA sign-in. We also wanted to ensure our solution had cross-platform support and didn't feel like a reinvention of the wheel. Hence, we settled on OAuth 2.0 and optionally the LiveSDK for authenticating with our APIs.
Another common piece of feedback from our developers was the need to 'learn by example'. So we upped the priority on launching our APIs with a working set of code samples in multiple languages, with complete auth integration. By the way, we'd love to hear your suggestions and any issues related to the code samples, tweet us at @onenotedev. We know it's nowhere near perfect:)
Register your app with Live connect and get a client ID
One prerequisite to using our auth model is for the developer to get a client ID and register their app with Live connect. We noticed that this step tripped up a few people so we decided to provide a step by step guide for major platforms (Android, iOS, Windows Phone, Windows Store apps) here. This way the documentation could cater to platform-specific instructions.
Some gotchas:
- When developing mobile apps for Android, iOS or Windows Phone, remember to select 'Yes' for the 'Mobile client app' field in the Basic Information settings.
- The steps for Windows Store applications are different. It needs a package identity instead of a client ID.
- Unfortunately, the same client ID cannot be shared between Windows Phone and Store apps because of conflicting settings. More here.
- These settings determine what gets displayed to the customer in the consent dialog (the dialog that requests for user's permission on behalf of your app). So be sure to provide a valid app name, logo and urls (if any) for the app's terms of service and privacy policy. There's a nice illustration of these settings and what part of the consent dialog they map to in the official Live connect documentation here.
Use the office.onenote_create and wl.offline_access scopes
A scope is basically a permission. It's the way your app can request the user give permissions to do specific things and the mechanism used by the OneNote API to ensure that your app has the necessary access privileges. Documentation here.
Some gotchas:
- Since the OneNote API currently supports creating new pages, the only scope we require for that operation is office.onenote_create. You can find more in-depth information in the Live Connect Developer Center Scopes and permissions documentation. Be sure to include the office.onenote_create scope in your auth code to avoid getting a 401 -Unauthorized response back from the API (scope names are case-insensitive). Truth be told, adding this scope to existing Live connect auth code is the *only* extra requirement for calling the OneNote APIs. So for those with previous Live connect experience this should all be pretty familiar.
- Tokens you receive using that scope will only be valid for one hour, so to avoid having to sign-in again and again, we also recommend you also request the wl.offline_access scope. If the user grants your app access, the token can be refreshed for up to a year, or until the user revokes their permission.
- We've also found from hacking around that wl.offline_access scope only works when added in conjunction with the wl.signin scope.
Lastly, there's quite a bit of existing resources on how to authenticate with Live connect (some of which I've linked above). I've personally found the following blog by Shelly Guo pretty useful. If you ever get stuck with auth and need us to investigate, please visit our StackOverflow page.
tl;dr get a client Id, use office.onenote_create scope, check out wl.offline_access wl.signin scopes too.
Ok, that was not the last thing:) To end on a completely random and unrelated note, I thought I'd share my latest, personal way of using the OneNote APIs. Here's how I use IFTTT and the OneNote APIs to get my fix of xkcd: