OAuth2 in action with the release of Office 365 Calendar, Contacts and Mail

  • Article

I bet everyone is equally excited like me to have the Office 365 API out of preview and generally available to start building super cool apps. For those entrepreneurs that worked with us through the preview, my colleague Rohit Agarwal posted a blog that summarizes the changes done to the Calendar, Contacts and Mail APIs in a nice concise way. Check it out here. As Rohit is looking out for the APIs, my focus is more on the authentication part, and especially on how to use OAuth2 to our APIs. If you missed my previous posts, check them out here:

 

· Using OAuth2 to access Calendar, Contact and Mail API in Office 365 Exchange Online

· Managing user consent for applications using Office 365 APIs 

· Enabling Microsoft Azure portal access to manage applications using the OAuth2 protocol

 

While not much changed on the OAuth2 front I thought it might be a good idea to provide a way to explore how OAuth2 works with our APIs. Over the past month this idea materialized in a little web app called "Office 365 OAuth Sandbox". It allows you to see how the OAuth2 protocol works with Azure AD, and see some limited pre-canned APIs in action that you might find useful. It is available on https://oauthplay.azurewebsites.net.

 

Before you check it out I want to make you aware of some points:

 

First the app uses the OAuth2 code flow as described Authorization Code Grant Flow.

 

Second, the app can be used in two modes. One mode allows you to use your own Office 365 user account to see the OAuth2 Consent and afterwards play with the pre-canned APIs. If you don't have an Office 365 tenancy or don't trust the web app to not do any harm, a second mode allows you to play with a sandboxed Office 365 tenant and a few different sandbox users that are setup with pre-populated data. The app prefills a sandbox account for you in the sign-on dialog. The password is displayed when hovering over the "Authorize using sandbox account" button.

 

Finally if you chose the mode to use your own Office 365 user account, remember you can always revoke access to the web app at https://myapps.microsoft.com.

 

Note if you use the sandboxed Office 365 tenant you might or might not see the Consent Dialog, as probably many people use the sandboxed tenant and already consented to the app. In good Microsoft manner my Office 365 developer company is Contoso. This means if you see the Consent Dialog you will see that the web app is developed by Contoso. The web itself is hosted in Windows Azure.

Other than that all the pre-canned API calls are read-only to the Office 365 data, but more important the app only asks and gets permissions to read calendar, contacts and mail data. The app never asks or is given any manipulative permissions to data. The read-only API calls are the same, regardless if you chose to use the sandboxed or your own Office 365 tenant.

 

Now, all I can add is to encourage you to play with the web app and listen to your feedback on the blog channel. But before I finish this blog, I want to say special thanks to my colleague Alex Park, as without him the web app would not have been available in this form to you. Also thank you to Shreedevi Padmasini who helped with great ideas, readjusted the pre-canned queries and helped getting all the sandbox Office 365 infrastructure in place.

 

With this. Happy play on https://oauthplay.azurewebsites.net.

 

Let us know how you like it!

 

Thank you!

Matthias Leibmann

 

 

FAQ:

Q: Why can't I play around with the APIs in the Office 365 OAuth2 sandbox?

A: The Office 365 OAuth2 Sandbox main goal was to show how the on-the-wire protocol looks like requesting access tokens for the Calendar, Contacts and Mail API. However we thought after getting access tokens you also want to see that those indeed work, thus we included some pre-canned APIs. However, there is a new API playground that focuses solely on playing with the API. Check it out, it is available here: https://apisandbox.msdn.microsoft.com

 

Q: The Office 365 OAuth2 playground only works with the Calendar, Contacts and Mail API, but not any of the other APIs. What about those?

A: Yes, that is true. We focused on showing the OAuth2 protocol and did not include all possible APIs. For this we do have the new API Playground (https://apisandbox.msdn.microsoft.com) that allows you to play with all the Office 365 APIs. You can get additional access tokens for these APIs by following the protocol as documented in Refresh Tokens for Multiple Resources.

 

Q: What other OAuth2 flows are available to build apps against the Office 365 APIs?

A: We are still working very hard to make the client credential flow (as described here) work briefly after GA, hopefully by end of the year. I will blog about this as soon as it is available.

 

Q: Can I use OpenID connect to provide SSO into my web app with an Organizational Account in Office 365

A: Yes, absolutely. We want you to use OpenID connect for all web apps that want to do SSO with Office 365. AAD supports OpenID connect as described in following article: OpenID Connect. There is also an example of using Calendar, Contacts, and Mail API from a single tenant ASP.NET MVC app using OpenId Connect available on Github here.

 

Q: Are there any more examples that help me quick start my project?

A: Absolutely yes. Check out https://github.com/OfficeDev for Office 365 examples or https://github.com/AzureADSamples. Fresh from the press is following Windows Store example for Calendar, Contacts and Mail API: https://github.com/OfficeDev/Office-365-APIs-Starter-Project-for-Windows.