Identity wrt310n validating want more

Friday, November 17, 2017 by Sali

Validate an Exchange identity token

  • 5 minutes to read
  • Contributors

Your Outlook add-in can send you an Exchange user identity token, but before you trust the request you must validate the token to ensure that it came from the Exchange server that you expect. Exchange user identity tokens are JSON Web Tokens (JWT). The steps required to validate a JWT are described in RFC 7519 JSON Web Token (JWT).

We suggest that you use a four-step process to validate the identity token and obtain the user's unique identifier. First, extract the JSON Web Token (JWT) from a base64 URL-encoded string. Second, make sure that the token is well-formed, that it is for your Outlook add-in, that it has not expired, and that you can extract a valid URL for the authentication metadata document. Next, retrieve the authentication metadata document from the Exchange server and validate the signature attached to the identity token. Finally, compute a unique identifier for the user by hashing the user's Exchange ID with the URL of the authentication metadata document.

The token returned from getUserIdentityTokenAsync is an encoded string representation of the token. In this form, per RFC 7519, all JWT's have three parts, separated by a period. The format is as follows.

The header and payload should be base64-decoded to obtain a JSON representation of each part. The signature should be base64-decoded to obtain a byte array containing the binary signature.

For more details on the contents of the token, see Inside the Exchange identity token.

Once you have the three decoded components, you can proceed with validating the content of the token.

Validate token contents

To validate the token contents, you should check the following.

  • Check the header and verify that:
    • The claim is set to .
    • The claim is set to .
    • The claim is present.
  • Check the payload and verify that:
    • Check that the current time is between the times specified in the and claims. The claim specifies the earliest time that the token is considered valid, and the claim specifies the expiration time for the token. It is recommended to allow for some variation in clock settings between servers.
    • Check that the claim is the expected URL for your add-in.
    • Check that the claim inside the claim is set to .
    • Check that the claim inside the is set to a valid URL.

Validate the identity token signature

After you know that the JWT contains the required claims, you can proceed with validating the token signature.

Retrieve the public signing key

The first step is to retrieve the public key that corresponds to the certificate that the Exchange server used to sign the token. The key is found in the authentication metadata document. This document is a JSON file hosted at the URL specified in the claim.

The authentication metadata document uses the following format.

The available signing keys are in the array. Select the correct key by ensuring that the value in the property matches the value in the header of the token. The public key is inside the property in the property, stored as a base64-encoded byte array.

Once you have the correct public key, verify the signature. The signed data is the first two parts of the encoded token, separated by a period:

Compute the unique ID for an Exchange account

You can create a unique identifier for an Exchange account by hashing the authentication metadata document URL with the Exchange identifier for the account. When you have this unique identifier, you can use it to create a single sign-on (SSO) system for your Outlook add-in web service. For details about using the unique identifier for SSO, see Authenticate a user with an identity token for Exchange.

Use a library to validate the token

There are a number of libraries that can do general JWT parsing and validation. Microsoft provides two libraries that can be used to validate Exchange user identity tokens.

System.IdentityModel.Tokens.Jwt

The System.IdentityModels.Tokens.Jwt library can parse the token and also perform the validation, though you will need to parse the claim yourself and retrieve the public signing key.

The class is defined as follows:

For an example that uses this library to validate Exchange tokens and has an implementation of , see Outlook-Add-In-Token-Viewer.

Microsoft.Exchange.WebServices

The Exchange Web Services Managed API can also validate Exchange user identity tokens. Because it is Exchange-specific, it implements all of the necessary logic to parse the claim and verify the token version.

Additional resources

https://docs.microsoft.com/en-us/outlook/add-ins/validate-an-identity-token