Edit

Share via

Authenticate a user with a single-sign-on token in an Outlook add-in

  • Article

Single sign-on (SSO) provides a seamless way for your add-in to authenticate users (and optionally to obtain access tokens to call the Microsoft Graph API).

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. Optionally, you can also have your server-side code.

  • 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 an overview of SSO in Office Add-ins, see Enable single sign-on for Office Add-ins and Authorize to Microsoft Graph in your Office Add-in.

Enable modern authentication in your Microsoft 365 tenancy

To use SSO with an Outlook add-in, you must enable Modern Authentication for the Microsoft 365 tenancy. For information about how to do this, see Enable or disable modern authentication for Outlook in Exchange Online.

Register your add-in

To use SSO, your Outlook add-in will need to have a server-side web API that is registered with Azure Active Directory (AAD) v2.0. For more information, see Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.

When you are developing an add-in, you will have to provide consent in advance. For more information, see Admin consent.

Update the add-in manifest

The next step to enable SSO in the add-in is to add some information to the manifest from the add-in's Microsoft identity platform registration. The markup varies depending on the type of manifest.

  • Add-in only manifest: Add a WebApplicationInfo element at the end of the VersionOverridesV1_1 VersionOverrides element. Then, add its required child elements. For detailed information about the markup, see Configure the add-in.

  • Unified manifest for Microsoft 365: Add a "webApplicationInfo" property to the root { ... } object in the manifest. Give this object a child "id" property set to the application ID of the add-in's web app as it was generated in the Azure portal when you registered the add-in. (See the section Register your add-in earlier in this article.) Also give it a child "resource" property that is set to the same Application ID URI that you set when you registered the add-in. This URI should have the form api://<fully-qualified-domain-name>/<application-id>. The following is an example.

    "webApplicationInfo": {
      "id": "a661fed9-f33d-4e95-b6cf-624a34a2f51d",
      "resource": "api://addin.contoso.com/a661fed9-f33d-4e95-b6cf-624a34a2f51d"
  },

Get the SSO token

The add-in gets an SSO token with client-side script. For more information, see Add client-side code.

Use the SSO token at the back-end

In most scenarios, there would be little point to obtaining the access token, if your add-in does not pass it on to a server-side and use it there. For details on what your server-side could and should do, see Add server-side code.

Important

When using the SSO token as an identity in an Outlook add-in, we recommend that you also use the Exchange identity token as an alternate identity. Users of your add-in may use multiple clients, and some may not support providing an SSO token. By using the Exchange identity token as an alternate, you can avoid having to prompt these users for credentials multiple times. For more information, see Scenario: Implement single sign-on to your service in an Outlook add-in.

SSO for event-based activation or integrated spam reporting

There are additional steps to take if your add-in uses event-based activation or integrated spam reporting (preview). For more information, see Use single sign-on (SSO) or cross-origin resource sharing (CORS) in your event-based or spam-reporting Outlook add-in.

See also