Posted by on Nov 16, 2015 in #Office365Dev | 0 comments

In Outlook add-ins there is a way to get an identity token with a simple JavaScript method (https://msdn.microsoft.com/en-us/library/office/fp142236.aspx):

You could use this identity token to verify Office 365 (Exchange) users in your own service – that means calling the getUserIdentityTokenAsync method and passing it with a call to your service. In example:

In this case, you will need to verify the identity token once it reaches your service. You might (will) also want to extract some user data to tie up everything in your backend.

This post is intended for anyone who is doing this without available libraries. There is an Exchange token validation library available for some .NET flavors: https://msdn.microsoft.com/EN-US/library/office/fp179840.aspx

For everyone else – let’s get on with it!

I created the following configuration file with the constant values needed for token validation. Make sure to configure your audience constant to match the source of your app.

Now define a couple of classes to map some of the JSON objects that we will deal with. I’m using the Newtonsoft Json.NET library (http://www.newtonsoft.com/json) to elegantly map between C# classes and JSON objects.

Let’s also create a static utility class to assist with some of the decoding. Thanks @PeterDrougge!

We can now start parsing the identity token and get into the nitty-gritty details of things. The identity token is a JWT, you can learn more about it here: http://jwt.io/

In short; the Exchange identity token (JWT) token consists of three parts (Base64Url encoded and split by a dot) – a header, the payload and a signature. The header contains information about the token, such as the token type and the algorithm used to secure it. The payload holds the information about the identity and the signature is the piece that verifies that the header and the payload has not been fiddled with.

I created the following class to hold the private and public data for the identity token. Everything will be done in the ParseAsync method, so I will keep an empty but private constructor.

In the ParseAsync method – let’s continue… I started out by assigning a couple of properties on the token object like so:

Next up we need to make sure that the token contains everything we need to validate it. We need to verify claims in the header and the payload – such as the audience, issuer, lifetime, and token version properties. I created a couple of methods to validate the various parts of the identity token.

Finally, when we know that everything we need is around – we can validate the token itself with the signature. This requires us to download the public part of the signing key, used to create the signature. It is located at the authentication metadata URL (found in the amurl property of the token).

Once you have the public key available, you can compute a SHA256 hash of the Base64Url encoded header and payload (combined together with a dot delimiter). Use any library to verify the hash with the signature – I’m using the RSACryptoServiceProvider class in this case (https://msdn.microsoft.com/en-us/library/system.security.cryptography.rsacryptoserviceprovider(v=vs.110).aspx)

With that, you can access and more importantly rely on the information given in the identity token! Use it to integrate the enormous amount of Office 365 identities with your service!

I catch the raw token in the request headers and parse it like so (ASP.NET Web API Controller):

View the entire ExchangeIdentityToken class here: http://simonjager.com/exchangeidentitytoken-cs/

-Simon Jaeger