Authenticate a mail add-in by using Exchange identity tokens

Office Add-ins

Learn how to use Exchange 2013 identity tokens to authenticate your mail add-in.

Last modified: August 06, 2015

Applies to: apps for Office | Office Add-ins | Outlook

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

In this article
Identity tokens
In this section
Additional resources

Your mail add-in can provide your customers with information from anywhere on the Internet, whether from the server that hosts the add-in, from your internal network, or from somewhere else in the cloud. If that information is protected, however, your mail add-in needs a way to associate the Exchange email account with your information service. Exchange 2013 can enable single sign-on (SSO) for your add-in by providing a token that identifies the email account that is making the request. You can associate this token with a registered user for your application so that the user is recognized whenever the mail add-in connects to your service.

Two of our sample add-ins 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 add-in can also access nonpublic information. You can use the server that hosts your add-in to link your add-in to the information in your internal network, or anywhere in the cloud.

You can use many different techniques to identify and authenticate add-in users. Exchange 2013 simplifies user authentication by providing your mail add-in 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 mail add-ins.

To use SSO in your add-in, the code does this:

  • Calls a function in the mail add-in 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 add-in, 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 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 add-in that sends the identity token and a list of phone numbers found in the message to a web service.



Inside the Exchange identity token

Describes the specific claims that are included in the token.

Call a service by using an identity token in Exchange

Provides code examples for mail add-in writers.

Use the Exchange token validation library

Provides code examples for using the .NET Framework validation library to write server-side code.

Validate an Exchange identity token

Provides code examples for implementing your own token validator.

Authenticate a user with an identity token for Exchange

Provides code examples for implementing a simple single sign-on system for a service.

© 2015 Microsoft