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:)
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.
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.
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:
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)
@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.
@DipakBoyed, Thanx for your reply.
I will refer to that code
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
@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.
it is very hard to find c# sample for asp.net.
Do have any plans to release one recently.......??
@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.
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'.
@MQJackson: Check out github.com/.../Desktop and see if it helps you with authentication in a desktop app.
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.
@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.