Authentication options in Outlook add-ins

Your Outlook add-in can access 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, your add-in needs a way to authenticate your user. Outlook add-ins provide a number of different methods to authenticate, depending on your specific scenario.

Single sign-on access token

Single sign-on access tokens provide a seamless way for your add-in to authenticate and obtain access tokens to call the Microsoft Graph API. This capability reduces friction since the user is not required to enter their credentials.

Note

The Single Sign-on API is currently supported for Word, Excel, Outlook, and PowerPoint. For more information about where the Single Sign-on API is currently supported, see IdentityAPI requirement sets. If you are working with an Outlook add-in, be sure to enable Modern Authentication for the Microsoft 365 tenancy. For information about how to do this, see Exchange Online: How to enable your tenant for modern authentication.

Consider using SSO access tokens if your add-in:

  • Is used primarily by Microsoft 365 users
  • Needs access to:
    • Microsoft services that are exposed as part of Microsoft Graph
    • A non-Microsoft service that you control

The SSO authentication method uses the OAuth2 On-Behalf-Of flow provided by Azure Active Directory. It requires that the add-in register in the Application Registration Portal and specify any required Microsoft Graph scopes in its manifest.

Using this method, your add-in can obtain an access token scoped to your server back-end API. The add-in uses this as a bearer token in the Authorization header to authenticate a call back to your API. At that point your server can:

  • Complete the On-Behalf-Of flow to obtain an access token scoped to the Microsoft Graph API
  • Use the identity information in the token to establish the user's identity and authenticate to your own back-end services

For a more detailed overview, see the full overview of the SSO authentication method.

For details on using the SSO token in an Outlook add-in, see Authenticate a user with an single-sign-on token in an Outlook add-in.

For a sample add-in that uses the SSO token, see Outlook Add-in SSO.

Exchange user identity token

Exchange user identity tokens provide a way for your add-in to establish the identity of the user. By verifying the user's identity, you can then perform a one-time authentication into your back-end system, then accept the user identity token as an authorization for future requests. Use the Exchange user identity token:

  • When the add-in is used primarily by Exchange on-premises users.
  • When the add-in needs access to a non-Microsoft service that you control.
  • As a fallback authentication (and authorization to Microsoft Graph) when the add-in is running on a version of Office that doesn't support SSO.

Your add-in can call getUserIdentityTokenAsync to get Exchange user identity tokens. For details on using these tokens, see Authenticate a user with an identity token for Exchange.

Access tokens obtained via OAuth2 flows

Add-ins can also access third-party services that support OAuth2 for authorization. Consider using OAuth2 tokens if your add-in:

  • Needs access to a third-party service outside of your control

Using this method, your add-in prompts the user to sign-in to the service either by using the displayDialogAsync method to initialize the OAuth2 flow, or by using the office-js-helpers library to the OAuth2 Implicit flow.

Callback tokens

Callback tokens provide access to the user's mailbox from your server back-end, either using Exchange Web Services (EWS), or the Outlook REST API. Consider using callback tokens if your add-in:

  • Needs access to the user's mailbox from your server back-end.

Add-ins obtain callback tokens using one of the getCallbackTokenAsync methods. The level of access is controlled by the permissions specified in the add-in manifest.