Tag: OAuth 2.0

Back in April I started writing a course for developing on Office 365.  Mainly focused on the O365 APIs (Mail, Calendar, Contacts and Files).  As part of building the course, I was able to provide quite a bit of feedback to engineering (check out my uservoice and the items that have since been implemented) on the various gaps that I found as compared to other similar platforms (both Microsoft and non-Microsoft).  The list was incredibly long and I wasn't particularly convinced that all of those items would be engineered anytime soon.  However as I was redoing my course, to my pleasant surprise, many of those suggestions had been implemented in a very short time!

Tools, Tools and more Tools

In the preview, you have to install two different sets of tools.  Those were rolled into a single installer package that points to a Web Installer that will always grab the latest for you.  That particular package as of 11/2014 is in Update 3 status.  You can download the tool here (forgive the fact that the .exe may be named "OfficeToolsForVS2013Update1.exe", again it is a web installer package and grabs the latest).  You can also follow Chakkaradeep's blog for all the latest on the tools as they continue to evolve (http://chakkaradeep.com/):

http://aka.ms/officedevtoolsforvs2013

Note that if you try to "Add Connected" service and end up with a set of *ApiSample files added, then you still have the old tools installed (this happened to me as I have many different Visual Studio clients on various machines).  This of course will cause problems if you try to open the new *working* samples mentioned below.  You will need to uninstall those old tools and add the new tools via the link referenced above.  This sample code is now part of the tools via "Client" classes that you can now choose to use or you can simply create your own.

NOTE:  In some cases you may find you have some older MVC project templates, if you create a new one and switch it to use the "Organizational Accounts" for its auth, it will add a "UserProfile" action that has older ADAL code in it (this has nothing to do with the O365 tools that you have installed and is part of the ASP.NET Identity team's code).  Any time you try to load the newer samples, the ADAL package will get upgraded using NuGet and the UserProfile action will not compile.  It is best just to delete it or update your Visual Studio to have the latest templates and recreate the project.

Samples, Samples and more Samples

The original page for all the O365 API preview stuff has been deprecated (http://msdn.microsoft.com/en-us/library/office/discovery-service-rest-operations%28v=office.15%29.aspx) and it now lives here:

http://msdn.microsoft.com/en-us/office/office365/howto/platform-development-overview

You can get O365 API samples here:

http://dev.office.com/code-samples

And they are copied directly to GitHub here:

https://github.com/OfficeDev

This is in contrast to the ones you will find on MSDN that are probably not up-to-date and do not compile with the new tools (think – the old Authenticator class or broken auth flows):

 https://code.msdn.microsoft.com/windowsapps/Office-365-APIs-How-to-use-609102ea

The core Azure AD samples (nothing to do with O365) that you should be using are here:

https://github.com/AzureADSamples

and a description of each is here:

http://msdn.microsoft.com/en-us/library/azure/dn646737.aspx

Note that the sample code on these pages use some hidden tricks for the Auth.  Notably, it is using OWIN on MVC app startup that create and initalize the cache in the AuthenticationContext class (NOTE, this code was developed by Andrew Connell and is pretty freakin awesome, be sure to thank him next time you see him as I can only imagine the time he put into this).  This context is then used to request an access token for you using the refresh token from the first "hidden" OWIN request.   If you are creating an application from scratch and not using these samples, you will not have this OWIN code and therefore are missing the first leg of the auth.  Even though the samples compile and Azure AD gives you back a token, you will not be able to use that token!  You must have a user context in order to be able to make calls to the O365 API endpoints. Simply sending the clientId and clientSecret will not establish a user context (although the platform will give you a useless/stupid access token). This is because Azure AD is used for access control with external custom applications (by extending the consent framework) that have nothing to do with O365 and may not even need such an advanced user context created and thusly, it is simply used for OAuth (reference the Azure ToDoService example).

Compiling samples (hints and tricks):

The samples utilize several different packages.  These include the ones on this page (http://msdn.microsoft.com/en-us/office/office365/howto/adding-service-to-your-Visual-Studio-project#O365NuGets), and a couple of extras:

• Azure Active Directory Auth Library (ADAL) – note current stable is 2.12, with 3.x in pre-release.  Some of the samples you may come across are using code in previous and later releases.  I have found it best to just update all the way, then figure out how to get the older code to work (which in some cases will take a really long time).  As an example, you may see that the Sync and Async methods for getting an access token may or may not exist and the various overrides for them may not be present.  It is very painful trying to figure out what changes were made from v1->v2->v3 as the code has changed so much.  This has nothing to do with the O365 API/SDK aspect (they have to deal with it just like we do), and more on the Azure tools team's side.

You should be aware that if you try to load a sample and it has any reference to the "Authenticator" class, that sample is now out of date and has a net worth of just about zero.  

Using the discovery service –

• When asking for permission for the discovery service, be sure to use "https://api.office.com/discovery/" and not "https://api.office.com/discovery" – note the extra slash at the end
• You should also ensure that your API calls go to "https://api.office.com/discovery/v1.0/me" and not "https://api.office.com/discovery/me" – note the version in the URL – some of the O365 API page examples have not been updated to show this
• You should definitely use the discovery service now to get your service endpoints.  The reason to do this is you may not know the O365 endpoint for a user's SharePoint ahead of time and the now defunc resource string "Microsoft.SharePoint" does not work anymore.  You must specify the authority/resource such as https://domain.sharepoint.com or https://domain-my.sharepoint.com, otherwise your request will fail (but will still work with the old preview APIs).

Note that all APIs are now returning ODATA v4.0 responses for JSON (no more result.d.results, it is result.value):

http://www.odata.org/documentation/odata-version-4-0/

Various things:

• You should also note that your "Accept" HTTP header should be set to "application/json" and not "application/json; odata=verbose" or you will get an error. 
• The structure of the JSON posts have changed.  You will notice the addition of the "EmailAddress" parent for email addresses now
• Mail endpoint changed from "/Messages/('id')" to "/Messages/{MessageId}"
• For new events, you cannot pass the "Status" the way you did before, it has changed its schema as well
• JSON Error messages are now results.error.message rather than results.error.innermessage.message
• Other than the endpoint for the O365 APIs, nothing really changed much in the "Contacts" api, your code should still work after making the endpoint change
• Files API now has the "me" endpoint!  This was one of the big asks that I had when I first looked at the O356 APIs in respect to the OneDrive for Consumer API offering (ref this blog post).  The consumer team has moved their API to the OneDrive for business and it is just plan AWESOME!
• Files API no longer requires SharePoint like RequestDigests in the headers!
• Uploading a file is done via a PUT, not a POST (you still have to put the binaryStringRequestBody header in the request
• The older way of telling the API that you want to overwrite a file has changed to have the parameter "nameConflict=overwrite"
• .JSON files are blocked by SharePoint, so don't try with the API or you get a 404 error
• When deleting a file, you must provide the "if-match" header with "*" or a matching tag, or the call will fail (an empty header will fail)
• I'd guess that the "/me/drive" endpoint will go away in V2 as we will have unlimited storage soon

Mobile and Cordova

• Samples on the O365 Dev site are out of date with the new tools (https://github.com/OfficeDev/TrainingContent/tree/master/O3654-2%20Deep%20dive%20into%20Mobile%20Development%20with%20Office%20365%20and%20Cordova)
• As of 11/2014, the latest tool version is 0.3.  It can be downloaded here link
• The location of the service scripts files has changed to be /services/office365/scripts
• The settings.js does not have the references to all needed files and it has been moved to another file called "o365loader.js".  You should add a reference to this on your html pages.
• You will need internet access to compile your first project (npm downloads and such)
• The Exchange namespace is gone, it is now Microsoft.OutlookServices
• If you get an error in your Ripple Emulator, I found that if you had a previous version, it doesn't work with 0.3 – ref this post.
• Try running "npm install -g ripple-emulator" to get the latest
• It is also possible you will get a "windows.open" error like "gap:["App","show","App590841629"]".  This simply means you have a loading error in one of you JS files, fix it and the window.open event will be handled properly
• The Ripple Emulator is set to use a dynamic port when your application starts.  This means the default port of 4400 that the VS code is expecting will not work.  You will need to change the Settings.js file to have the proper port and then update your Azure AD to have the matching port in the redirectUri
• In the Ripple Emulater, be sure to change the cross domain from "Local" to "Remote" or you will get errors when making O365 API calls
• There are some other issues with the current build (notably many related to Windows Phone development) – ref this post
• If you get an error around the inappbrowser plugin, you have to stop debugging and then try try again…eventually it should come around (you may find you have to do this in several occasions as it seems there may be some race conditions occurring somewhere)
• The official Android samples from the O365 team are here. They use Eclipse and are much easier to get up and running with as they have setup instructions.
• MS Open Tech Group Android samples have been updated to the new V1 API and are now using Android Studio rather than Eclipse, but you are on your own to get them up and running.

Now, once your environment is up and running, you may run into some interesting challenges. 

The First is with the consent framework.  If you ever give your application the "Have full access to users' mailbox", your mail token will be worthless with "Access Denied".  Simply remove that from your app permission set and viola, your requests will work again.  This seems to be a bug in V1.0

Secondly is that you cannot simply call the code on this page without the first leg of the auth (getting an access code first):

http://msdn.microsoft.com/en-us/office/office365/howto/common-file-tasks-client-library

Third, you cannot use a service token generated from the "common" authority.  It must be from "your" tenant authority…ie…

https://login.windows.net/Common vs https://login.windows.net/tenantID

If you do this, the request will fail.  NOTE:  Andrew C. mentioned that this should work, but I think their are some outlier cases that this does not work (such as what I am seeing in some of my course labs).

Fourth, a token is only good for the resource that you requested. It cannot be used for any other resources and there is no way (unfortunately), to put in more than one resource (would be nice to do "https://graph.windows.net;https://acs579.sharepoint.com" with the scopes union-ed). This directly leads to the fifth point…

Fifth, Azure AD cannot handle double hops very well.  Consider the following situation (User->Client->WebAPI->O365) described as:

• Create a WebAPI project with a web app on the Azure side (it is created
  with custom permissions and given O365 SharePoint permissions).
• Add the Azure auth code into the OWIN part to validate a bearer token from client apps
• Add some method calls to make a call to O365 apis
• Create a windows 8 client app with a native client app on the Azure side (give it the custom permissions)
• Run the windows 8 app, login as a user to that app (code flow is initiated with resource target)
• Code flow is initiated, tokens generated (access and bearer) – notice how only the scope of the target resource is sent back
• Send the access token in the authentication header, add the refresh token to the basic headers
• Analyze the token claims looking for the custom permission, continue on to access O365 SharePoint if present
• Attempt to use the webapi client id and secret with the refresh token to get a new access token for the "https://domain.sharepoint.com" resource
• Attempt to use the token…get slapped in the face with a "client_secret is invalid message", but I know 100% it is valid…*in all likeliness this is a bug in the current Azure AD version*

I have yet found a way to support this type of user flow with Azure AD (User->Client->WebAPI->O365).  Obviously the user will never be able to respond to any prompts from the webapi as it is headless and hidden away on some network far far away.  It would be great if I could pass the first access token in an auth flow to Azure with valid clientid and secret to simply generate a new access token for a second resource.  I have no idea why I have to keep passing a refresh token around (one that doesn't even seem to work when used with a client id that it was not generated with in the first place) in all my apps just to get a new token.  IMHO, It's incredibly wasteful and not very well designed.

So there you go, just a few helpful hints for your O365 API journey if you came from preview days.  I'll keep updating the post as I go…

Chris