This sample shows you how to use a client token from the Exchange server to provide authentication for users of your mail app. The Exchange server issues a token that is unique to the mailbox on the server; you can use this token to associate a mailbox with services that you provide to a mail app.

The sample is divided in two parts. The first part, the mail app, runs in the email client. It requests an identity token from the Exchange server and sends this token to the second part, a web service that processes the request from the client.

The service uses the following steps to process the token:

• It validates the token to make sure that it was sent from an Exchange server, and that the token was intended for this mail app.

• It searches a local dictionary to determine whether the unique identifier has been used before. If the unique identifier has not been used, the service requests credentials (service user name and password) from the client. If the unique identifier is present in the token cache, the service sends a response.

• If the request contains credentials (that is, it is a response to a request for credentials), the service stores the service user name in the token cache with the unique identifier from the token as its key.

This sample does not validate the service user name and password in any way. A credential request is considered valid if it contains both a user name and password. Credentials do not expire from the cache in this sample; however, all the cached identifiers and user names are lost when you stop running the sample application.

This sample requires a valid server certificate on the Exchange server. If the Exchange server is using its default self-signed certificate, you will need to add the certificate to your local trusted certificate store. You can find instructions for exporting and installing a self-signed certificate on TechNet.

This sample requires that you have the following:

• Visual Studio 2012, with the apps for Office project templates.

• A computer running Exchange 2013 with at least one email account, or an Office 365 developer account.

• Microsoft.Exchange.WebServices.Auth.dll - This library is included in the Exchange Web Services (EWS) Managed API. You can download the EWS Managed API from the Microsoft Download Center.

• Microsoft.IdentityModel.dll - This library is included in the Windows Identity Foundation SDK. You can download the SDK from the Microsoft Download Center.

• Microsoft.IdentityModel.Extensions.dll - This library is available for download from one of the following locations:

  • Windows IdentityModel.Extensions.dll for 32-bit applications

  • Windows IdentityModel.Extensions.dll for 64-bit applications

• Familiarity with JavaScript programming and web services.

The sample solution contains the following file in the IdentityToken project:

• IdentityToken.xml -Manifest file for the mail app.

The IdentityTokenService project defines a REST service by using the WCF API. The project was created by using the WebAPI wizard in VisualStudio 2012. The project contains the following files:

• Controllers\TokenServiceController.cs - The service object that provides the business logic for the sample service.

• Models\Config.cs - Provides string values that must be matched in the client identity token.

• Models\ServiceRequest.cs - The object that represents a web request. The contents of the object are created from a JSON request object sent from your mail app.

• Models\ServiceResponse.cs - The object that represents a response from the web service. The contents of the object are serialized to a JSON object when they are sent back to the mail app.

• Global.asax - The global file for the web service. The route table is configured for the REST service in the Application_Start event handler.

• Web.config - Binds the sample service to the web server endpoint.

The IdentityTokenWeb project contains the UI and JavaScript code for the mail app. The project was created by using Visual Studio 2012 and is based on the mail app project template. The following files were modified for this sample:

• App\Home\Home.html - The HTML user interface for the mail app.

• App\Home\Home.js - The JavaScript file that handles requesting and using the EWS request.

The mail app will be activated on any email message in the user's Inbox. You can make it easier to test the app by sending one or more email messages to your test account before you run the sample app.

Press F5 to build and deploy the sample application. Complete the following tasks to deploy the application:

1. Connect to an Exchange account by providing the email address and password for an Exchange 2013 server.

2. Allow the server to configure the email account.

You run and test the sample in the web browser that is started by Visual Studio when you build and deploy the sample.

Follow these steps to run the sample:

1. Log on to the email account by entering the account name and password.

2. Select a message in the Inbox.

3. Wait for the app bar to appear over the message.

4. In the app bar, click IdentityToken.

5. When the EWS Request mail app appears, click the Use Identity Token button to send a request to the Exchange server.

6. The server will ask you to log on. You can type anything in the service user name and password boxes. This sample does not validate the contents of the text boxes.

7. Select the Use Identity Token button again. This time a response is returned from the server without a request for a user name and password.

8. If you have another email message in your Inbox, you can switch to that email message, select IdentityToken, and then select the Use Identity Token button. The response will be returned from the server without a request for a user name or password.

The following are common errors that can occur when you use Outlook Web App to test a mail app:

• The App bar does not appear when a message is selected. If this occurs, restart the application by selecting Debug - Stop Debugging in the Visual Studio window, then press F5 to rebuild and deploy the app.

• Changes to the JavaScript code may not be picked up when you deploy and run the app. If the changes are not picked up, clear the cache on the web browser by selecting Tools - Internet options and clicking the Delete… button. Delete the temporary Internet files and then restart the app.

• Authenticating a mail app by using Exchange identity tokens

Updated the sample to use the latest APIs and templates.