Authenticating a mail app by using Exchange identity tokens

Two of our sample apps use publically available information – one shows a Bing map for addresses in a message, and one shows a preview for YouTube video links in a message. But your mail app can also access nonpublic information. You can use the server that hosts your app to link your app to the information in your internal network, or anywhere in the cloud.

You can use many different techniques to identify and authenticate app users. Exchange 2013 simplifies user authentication by providing your mail app an identity token that identifies a specific Exchange email account. You can associate this token in your service with a registered user, enabling single sign-on (SSO) for your customers that use Outlook.

To use SSO in your app, the code does this:

• Calls a function in the mail app API that returns an identity token.

• Sends the token together with a request to your server.

• Unpacks the response from the server to display information from your service.

On the server side, things are somewhat more complex. When your server receives a request from a mail app, the process works like this:

• The server validates the token. You can use our managed token validation library, or you can create your own library for your service.

• The server looks up the unique identifier from the token to see whether it's associated with a known identity. Your service must implement a method that matches the identifier with known users of your service.

• If the unique identifier matches an identifier previously stored with a set of credentials on the server, your server can respond with the requested information without requiring your customer to log on to your service.

• If the unique identifier is unknown, the server sends a response asking the user to log on with credentials for the server.

• If the credentials match a known identity on the server, you can map that identity to the unique identifier in the token so that the next time a request comes in, your server can respond without requiring an additional logon step.

Note
This is just one suggestion for how to use the identity token. As always, when you're dealing with identity and authentication, you have to make sure that your code meets the security requirements of your organization.

Let's get into the specifics. As an example, we'll use a simple mail app for Outlook that sends the identity token and a list of phone numbers found in the message to a web service.

• Advanced concepts for developing mail apps in Outlook 2013

• Calling web services from a mail app for Outlook