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:

Comments

• Anonymous
  April 07, 2014
  Thank you for the nice article. Just to check with you, since we are planing to integrate our gaming application with Microsoft OneNote, is there any way to do this authentication without prompting user to enter their username and password....?? (Assume that we have all username and passwords)

• Anonymous
  April 08, 2014
  @Asanka-Playware: As far as I can tell, the minimum requirement is that the user has to explicitly grant their consent to your app (e.g. allow app to create new pages). Check out our Windows Store code sample (github.com/.../OneNoteServiceSamplesWinStore) where  single sign-on is implemented (it comes built in with windows 8 and above) so the app doesn't has to ask user to re-enter their username/password.

• Anonymous
  April 08, 2014
  @DipakBoyed, Thanx for your reply. I will refer to that code

• Anonymous
  April 15, 2014
  Thank you for the info. There are examples for different platforms, but not the web. Is it possible to point me to a web example? thanks a lot

• Anonymous
  April 16, 2014
  @Hussain, we don't have a web specific code sample yet. But you can check out the links under 'Authenticate the user with REST" at : msdn.microsoft.com/.../dn575435(v=office.15).aspx You'll also need expand that section btw. Thanks

• Anonymous
  May 21, 2014
  it is very hard to find c# sample for asp.net. Do have any plans to release one recently.......?? Thank you

• Anonymous
  July 08, 2014
  @Asanka-Plaware: Check out blogs.msdn.com/.../getting-started-with-onenote-api-in-an-asp-net-mvc-application.aspx. It's a video of how to integrate oneNote APIs with an ASP.NET site.

• Anonymous
  November 08, 2014
  I would like to write a 'desktop' application (console app and/or WPF ... specifically NOT WinStore). Are there any samples for the authorization is such a case? You have android, iOS, Win Phone 7, Win Store but seems that desktop/console has been relegated to 'software Siberia'.

• Anonymous
  November 10, 2014
  @MQJackson: Check out github.com/.../Desktop and see if it helps you with authentication in a desktop app.

• Anonymous
  October 20, 2015
  This should be mentioned on the OneNote API docs somewhere. Spent the last couple of hours debugging authentication, forget about actually developing functionality. PS You might want to include office.onenote scope as well.

• Anonymous
  October 21, 2015
  @Varun Agarwal, at the time of this blog post's writing, we only had the single POST Pages API and the single office.onenote_create scope. We'll get the post updated to more clearly mention the other scopes needed by newer APIs we brought alive since then. Sorry to hear about your troubles. Hopefully you are all squared up now. We kinda knew Auth was non-trivial hence this post in the first place.