Secure Your Outlook Add-in: Mastering Exchange Identity Tokens

  • author-thumb
  • Alexey Panteleev
  • February 18, 2024

Update (October 2024): Microsoft has deprecated Exchange Identity Tokens

Ever wondered how your Outlook add-in seamlessly identifies users and connects them to your back-end services? The magic lies in a little-known hero: the Exchange Identity Token. In this blog post, we’ll unveil its secrets, explaining what it is, why it’s crucial, and how to handle it effectively.

What is an Exchange Identity Token?

Imagine a secure passport for your add-in users. That’s essentially what the Exchange Identity Token is. It’s a digitally signed message that confirms a user’s identity and grants access to your back-end services. Think of it as a handshake that eliminates unnecessary logins and streamlines the user experience.

Why is it Needed?

Security and convenience are the key drivers. By using tokens instead of passwords, you enhance security by avoiding sensitive information transmission. Additionally, users enjoy a seamless experience, avoiding repetitive logins and enabling smooth interactions with your add-in.

Understanding the Token Structure:

The token obtained from getUserIdentityTokenAsync is encoded as a base64 URL-encoded string and follows the JWT format, consisting of three parts:

  • Header: Contains information about the token format and signature algorithm.
{
  "typ": "JWT",
  "alg": "RS256", // The hashing algorithm that is used to create the signature. 
  "x5t": "Un6V7lYN-rMgaCoFSTO5z707X-4" // The X.509 thumbprint of the token.
}

  • Payload: Holds crucial claims like user identifier, server details, and validity period.

    The information in the appctx claim provides you with the unique identifier for the account and the location of the public key used to sign the token.

{ 
  "aud": "https://mailhost.contoso.com/IdentityTest.html", 
  "iss": "00000002-0000-0ff1-ce00-000000000000@mailhost.contoso.com", 
  "nbf": "1331579055", 
  "exp": "1331607855", 
  "appctxsender": "00000002-0000-0ff1-ce00-000000000000@mailhost.context.com",
  "isbrowserhostedapp": "true",
  "appctx": { 
    "msexchuid": "53e925fa-76ba-45e1-be0f-4ef08b59d389@mailhost.contoso.com",
    "version": "ExIdTok.V1",
    "amurl": "https://mailhost.contoso.com:443/autodiscover/metadata/json/1"
  } 
}
  • Signature: Ensures the token’s authenticity and originates from the expected Exchange server.

For more details see Inside the Exchange identity token

Handling the Token:

Now that you understand the structure, let’s delve into handling the token:

  1. Acquiring the Token: Use the getUserIdentityTokenAsync method in your add-in code.
  2. Sending the Token: Include it with every request to your back-end service, usually in a header or request body.
  3. Validating the Token: Verify the signature using the public key retrieved from the authentication metadata document referenced in the payload.
  4. Storing the Token: Treat tokens like temporary access keys. Don’t store them permanently and refresh them as needed.

Validating the Token: The Crucial Step

Extract the JSON Web Token (JWT)

The token obtained from getUserIdentityTokenAsync is encoded as a base64 URL-encoded string and follows the JWT format, consisting of three parts: header, payload, and signature. Before validation, decode the token to obtain the JSON representation of each part.

Validate Token Contents

Ensure that the token is well-formed and contains the necessary claims:

  • Check the header to verify that it specifies typ as JWT, alg as RS256, and x5t is present.
  • Verify the payload, ensuring the presence of essential claims such as amurl, nbf, exp, aud, and version.
  • Confirm that the amurl claim points to an authorized token signing key manifest file, and validate the domain for additional security.

Retrieve and Validate the Identity Token Signature

Retrieve the public signing key corresponding to the certificate used by the Exchange server to sign the token. This key is stored in the authentication metadata document, hosted at the URL specified in the amurl claim. Match the x5t value from the header of the token with the one in the authentication metadata document to select the correct key. Then, validate the token’s signature using the retrieved public key.

Compute a Unique Identifier for the Exchange Account

To create a unique identifier for the Exchange account, concatenate the URL of the authentication metadata document with the Exchange identifier for the account. This unique identifier can be used for single sign-on (SSO) systems for Outlook add-in web services.

Additional Considerations:

  • Clock Variation: Allow for some variation in clock settings between servers when validating the token’s expiration time (exp) and not-before time (nbf).
  • Domain Verification: Implement domain verification logic to ensure that the domain specified in the amurl claim matches the expected Autodiscover domain for the user.
  • Public Key Retrieval: Ensure the correct retrieval and matching of the public key for signature validation, as specified in the authentication metadata document.

For more details see Validate an Exchange identity token

Automating Identity Token Validation and Session Management

While Exchange Identity Tokens offer robust security and convenience, managing their validation and leveraging them for user sessions can be an intricate task. This is where Aurinko steps in, acting as your secret weapon for efficient and secure add-in development.

Imagine a platform that simplifies the complexities of Exchange Identity Tokens. Aurinko does just that! It automates the entire validation process, taking care of:

  • Signature verification: Ensures the token is genuine and originates from the intended Exchange server.
  • Claim examination: Validates claims like user identifier and expiration time, guaranteeing the token’s legitimacy.
  • Public key retrieval: Fetches the necessary public key from the authentication metadata document for secure verification.

With Aurinko handling these critical steps, you can focus on building the core functionality of your add-in, saving valuable time and effort.

See Aurinko API refs.

The Power of Linking Tokens to Aurinko Users

But Aurinko doesn’t stop there! It seamlessly links validated tokens to existing Aurinko user records, unlocking powerful session management capabilities:

  • Single Sign-On (SSO): Users enjoy a seamless experience, logging in once to access both your add-in and other Aurinko-integrated accounts.
  • Persistent Sessions: Eliminate repetitive logins within your add-in, enhancing user convenience.
  • Secure Access Token Storage: Provide secure access to other non-Microsoft Aurinko-integrated accounts for your add-in users.

See Aurinko API refs.

Conclusion

Exchange Identity Tokens are indispensable for maintaining secure communication between Microsoft Exchange servers and external services or add-ins. By understanding their structure and implementing best practices for handling them, developers can ensure the integrity and security of their applications in the Exchange environment.

Don’t let the complexities of Exchange Identity Tokens hinder your add-in’s potential. You can quickly integrate Aurinko into your development workflow and streamline your Outlook add-in development.

Related Content