Transitioning from O365 Preview to O365 V1

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 (

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 ( and it now lives here:

You can get O365 API samples here:

And they are copied directly to GitHub here:

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):

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

and a description of each is here:

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 (, 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 "" and not "" – note the extra slash at the end
  • You should also ensure that your API calls go to "" and not "" – 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 or, 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):

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 (
  • 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 "" error like "gap:["App","show","App590841629"]".  This simply means you have a loading error in one of you JS files, fix it and the 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):

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

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 ";" 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 "" 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…



O365 and Non-ADFS Federation – It’s not O365’s fault

I'm not a fan of ADFS.  It sits right below Azure Access Control Services (ACS).  ACS used to be my favorite identity provider aggregation platform, but how times change (ref this post).  Several new players are entering the market and all of them realize the missing gaps in ADFS and ACS.  Therefore, the drive to make a better authentication toaster is ON!

The goal of this post is to make you realize that you are having the wool pulled over your eyes in terms of the bigger picture around Identity Management when it comes to O365.  To make this point, let's take a look at a typical on-premises solution:

  • A SharePoint customer wants to setup multiple site collections (yes, all host header site collections) to support different customers
  • Each customer has different requirements around supporting federated external customers
  • Some customers prefer Google as their auth, others Yahoo and others Facebook, etc


Solving this problem with on-premises environments is a piece of cake.  You have complete control over adding trusted Identity Providers (IdP) all day long. To solve the problem above, its likely you are going to think that adding a Trusted Identity Provider for each required auth mechanism is the answer.  That would be false.  As tempted as you may be to do this, its a really bad idea to have more than one. You should ultimately have a single Identity Provider with that provider supporting multiple "Apps/Replaying Parties (in this case site collections)" that would then show different options when a user needs to auth.  This allows you the most flexibility in that you simply set the IdP once, then configure the apps in the IdP.  Totally seamless, perfect.

Office 365 and Single Sign On (ADFS)

If you had this requirement in O365, you are out of luck.  Do not pass GO, do not collect $200USD.  In terms of O365, you are by default forced to use this one IdP mentality.  For each verified O365 domain, you can only setup a single Federated Identity Provider.  In most cases, everyone I have seen has used ADFS to integrate their on-premises Active Directory to sync accounts and/or configure Single-Sign On to redirect to their ADFS proxy.  This unfortunately, is the Microsoft promoted way of achieving Single-Sign-On nirvana.  I'm not a baby swimming in a pool, so let's take a look at what lives outside the koolaid-y-ish sugar water.  If you do this (which unfortunately, you probably already have), you are locking yourself into the current limited features of ADFS and hoping that ADFS gets some much needed development attention in the future (such as supporting OAuth 2.0). That being true, ADFS is a Microsoft product, you'll find a lot of people that can help you (support and consultant resources) to get it setup within a few hours.  You could also do it yourself by using TechNet/MSDN et all. 

Office 365 and Something else

If you want to use something other than ADFS, well, you better dig in for doing a ton of research on how WS-Fed and WS-Trust works and similarly, OAuth.  If you don't have time for that, then you'll need to request the services of people that do know that space. Unfortunately, having the identity management skills matched with an understanding of the future of App Models across vendors is a rare breed of consultant.  You also have to contend with a cold hard fact:

  • Currently, Office 365 only supports users of your verified domains (such as

Say what?  It means that even if you wanted to use Twitter, Facebook, whatever, the people that signed up have to have used the email address from their verified domain!  Uh…say that again?  Yeah, that means you can't login with your account using Facebook.  If you signed up with your account on Facebook, then it will likely map your email over in the claims and let you in, but that's up to how fancy your Identity Provider is.  Azure AD is expecting a very specific format of token with specific claims.  If it doesn't get them, then your login will fail.

So if you can't login using something other than a verified account, what's the point?  

I feel this is a major fundamental loss of functionality between on-premises and O365.  If I want to create a site collection with a specific relaying party app to my IP (which then provides a set of auth services), I should be able to do it. It is such a common pattern in on-premises SharePoint. I don't think the band aid of "external access" fits the bill here.  Those links that are generated can be freely sent all over the web punching small barely noticeable holes in your O365 tenant. I'd like to see the governance page in O365 that shows me every link that has been generated across the entire tenant (you can see on a site by site basis using this link –  There is not global admin UI to tell you who has been added or what has been shared – reference notes at bottom of this article. With an IdP in the picture, you simply disable their access and now they will never gain access to anything in your environment. This would require the removal of this "external sharing" feature that bypasses Azure AD in O356.  Wow, isn't that innovative?

Can I even use something other than ADFS in O365?

Heck yeah you can!  I recommend it!  By adoptingchoosing an Identity Provider solution (whether one you install on-premises or cloud hosted) that allows for you to expand
out past basic AD accounts, you will be ready for when Azure and O365 wakes up one day to
realize they should have allowed it in the first place.  You can set this up by removing the ADFS federation and replacing it with new Ws-Fed endpoints of your IdP.  This is enabled using the following cmdlets (this one is using

  • $cred = Get-Credential
  • Connect-MsolService –Credential $cred
  • Set-MsolDomainAuthentication -DomainName "" -FederationBrandName "" -Authentication Federated -PassiveLogOnUri "" -ActiveLogonUri "" -MetadataExchangeUri "" -SigningCertificate "Cert" -IssuerUri "urn:chrisgivens" -LogOffUri "" -PreferredAuthenticationProtocol WsFed 

NOTE:  If you have already setup ADFS, you'll need to disconnect from that.  I have yet to test out all the paths, but the one I choose was really painful.  I used the Remove-MsolFederatedDomain cmdlet.  This forced me to remove all users (but did not require me to remove my groups).  Once I removed all users the command succeeded, but proceeded to delete the domain completely from my tenant!  I then had to re-add it, re-verify it, then fire off a DirSync.  Once that once done, I could run the above commands and it redirected properly to my IdP.

After configuring the federation when you go to "" and type your verified email, it will redirect to your IdP login page.  From there, you will see all the options that you have enabled for that relaying party.  Even though you can enable all the OAuth 2.0 providers you can imagine, an attempt to login will fail miserably.  There are some current technology issues that Azure AD must resolve:

  1. Azure expects a UPN/Email that matches a user in your Azure AD (at a minimum, you would have needed to sign up for a service using that verified domain email)
  2. Azure AD is expecting an ObjectID
  3. O365 Services have to support these accounts (even if that means simply ignoring them)

For the first issue.  Azure AD would have to allow the addition of users other than your verified domain.  Or at your IP, you map a user from external to internal.  For the second issue, again, this can resolved by either Azure, or by the Identity Provider.  IPs can choose to implement this today by integrated with Azure AD to query for the object id based on a valid UPN.

Until this these items are resolved, you can certainly fall back to the "forced" way by Microsoft to use Active Directory users from a verified domain (and yes, you should feel angry about this) by setting up a pass through from your IP to ADFS/Active Directory.  The preferred way is to utilize a client on your Active Directory server (pretty much every IdP has this). As only a few of you know or will understand, if you use ADFS, you will currently lose Office Client features. But don't be worried, later this year, Office will release an update that will support SAML-P.  This will let you utilize many different types of auth (basically anything you can do via browser) with Office clients.  That will be awesome, even though users will never fully understand what just happened.

Take It Up Another Level

Home realm discovery is not extensible in Azure AD.  What is home realm discovery?  Its the login drop page that takes your context, in this case, your email domain, and then redirects you to the proper IdP.  What does it mean to not be extensible?  It means that IdP's cannot create a portal of Apps page.  What does that mean?  Think Universal Access Gateway (UAG).  Imagine UAG-like portals, only hosted by your IdP, such that an external party can login to your IdP, and are then presented with the applications (such as O365), that they have access too.  When they select it, it will immediately redirect you to your O365 site (no need to go to  As it stands right now, O365 does not support external home realm discovery pages.  This is also a serious limitation that needs to be added to the road map.


If enough people push the O365 and the Azure teams to fill the gap of this major difference between the products, I feel it would fulfill many of the requirements we have with customers today and make O365 an even more popular platform!  Here is your call to action:

  • Quit using ADFS, find an IdP with an eye towards the future
  • Highly "Suggest" to Azure and O365 that they support external identities (Vote for it here on UserVoice)
  • "Suggest" to Azure that they allow tenants to have a custom home realm discovery page

Stay classy internet,