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.
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.
If the add-in is using the Teams manifest for Office Add-ins (preview), there is some manifest configuration, but Microsoft Graph scopes aren't specified. SSO-enabled add-ins that use the Teams manifest can be sideloaded, but can't be deployed in any other way at this time.
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 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 services from Microsoft and others that support OAuth2 for authorization. Consider using OAuth2 tokens if your add-in:
- Needs access to a 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.
- 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.
Submit and view feedback for