Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

Authenticate a mail app by using Exchange identity tokens

apps for Office

Learn how to use Exchange 2013 identity tokens to authenticate your mail app.

Last modified: April 02, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Identity tokens
In this section
Additional resources

Your mail app can provide your customers with information from anywhere on the Internet, whether from the server that hosts the app, from your internal network, or from somewhere else in the cloud. If that information is protected, however, your mail app needs a way to associate the Exchange email account with your information service. Exchange 2013 can enable single sign-on (SSO) for your app 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 app connects to your service.

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 mail apps.

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

Article

Description

Inside the Exchange identity token

Describes the specific claims that are included in the token.

How to: Call a service by using an identity token in Exchange

Provides code examples for mail app writers.

How to: Use the Exchange token validation library

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

How to: Validate an Exchange identity token

Provides code examples for implementing your own token validator.

How to: Authenticate a user with an identity token for Exchange

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

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.