Mail Apps and OAuth (AKA “Your Mail App is Busted”)

Jens has a really good post over on his blog about an issue he faced trying to configure OAuth integration between Lync Server 2013 and Exchange Server 2013:

https://blogs.technet.com/b/jenstr/archive/2012/11/22/getting-internal-server-error-500-when-creating-new-cspartnerapplication-for-exchange-2013.aspx

Why do I point this out? Because the same issue he saw is the one that’s been causing my Message Header Analyzer app for Office to fail in some environments. So far, I’ve only gotten one bad review:

Loads into mail preview grey bar okay but doesn't work. 
1. Something went wrong and we couldn't start this app. Try again.
then retry
2. This app may not load properly
then start
'Message Header Analyser' title appears.
thats it.

It turns out, that’s a symptom of Jens’ OAuth problem! The customer actually has an issue they need to correct in their environment. If you’re out there Richard Collins, this article is for you!

The Problem

Here’s what typically happens:

  1. Administrator installs an App for Outlook that requires Restricted Permissions.
  2. User activates this app on a message in OWA.
  3. The app attempts to make an EWS request.
  4. As part of making this request, the framework needs to get an access token.
  5. The request for the access token fails. The EWS call is never actually made and an error is returned to the app.
  6. How the app handles the error is dependent on the app, but whatever functionality depended on the EWS call is now broken.

In the case of Message Header Analyzer – it just stops rendering. I could perhaps handle this case more gracefully, and might in the future. Other apps display an error to the user.

Under the Covers

If we use F12 in IE to look at the network traffic, we’ll see the final frame’s request looks something like this:

 {"__type":"GetClientAccessTokenJsonRequest:#Exchange",
   "Header":{"__type":"JsonRequestHeaders:#Exchange",
      "RequestServerVersion":"Exchange2012",
      "TimeZoneContext":{"__type":"TimeZoneContext:#Exchange",
         "TimeZoneDefinition":{"__type":"TimeZoneDefinitionType:#Exchange",
            "Id":"Eastern Standard Time"
         }
      }
   },
   "Body":{"__type":"GetClientAccessTokenRequest:#Exchange",
      "TokenRequests":[
         {"__type":"TokenRequest:#Exchange",
            "TokenType":"ExtensionCallback",
            "Id":"62916641-fc48-44ae-a2a3-163811f1c945"
         },
         {"__type":"TokenRequest:#Exchange",
            "TokenType":"ExtensionCallback",
            "Id":"d39dee0e-fdc3-4015-af8d-94d4d49294b3"
         },
         {"__type":"TokenRequest:#Exchange",
            "TokenType":"ExtensionCallback",
            "Id":"f60b8ac7-c3e3-4e42-8dad-e4e1fea59ff7"
         }
      ]
   }
}

This will be met with an error. The exact error appears to depend on the version of Exchange 2013, but I’ve seen both a GetClientAccessTokenResponseMessage with the text “The token for this extension could not be retrieved.” as well as a 503 Service Unavailable. In both cases, when we checked Get-AuthConfig , we found a thumbprint which was not present on any of the certificates found when we ran Get-ExchangeCertificate. Following the steps in Jens’ article to ensure that the thumbprint listed in Get-AuthConfig matched a cert in Get-ExchangeCertificate allowed OAuth to work, in turn allowing the App to work.

Conclusion

Administrators: If you find a mail app can load, but doesn’t function, it might be a problem with your OAuth configuration. Check your F12 trace to see if the GetClientAccessTokenRequest frame is the one that fails. If it is, check your OAuth configuration.

Developers: If your mail app uses EWS, be on the lookout for this sort of error and react appropriately. I suggest directing the user to someone who can help their administrator check the OAuth configuration.