Extend a Teams personal tab across Microsoft 365

Personal tabs provide a great way to enhance the Microsoft Teams experience. Using personal tabs, you can provide a user access to their application right within Teams, without the user having to leave the experience or sign in again. With this preview, personal tabs can light up within other Microsoft 365 applications. This tutorial demonstrates the process of taking an existing Teams personal tab and updating it to run in both Outlook desktop and web experiences, and also Office on the web (office.com).

Updating your personal app to run in Outlook and Office involves these steps:

  • Update your app manifest.
  • Update your TeamsJS SDK references.
  • Amend your Content Security Policy headers.
  • Update your Microsoft Azure Active Directory (Azure AD) App Registration for Single Sign On (SSO).
  • Sideload your updated app in Teams.

The rest of this guide walks you through these steps and show you how to preview your personal tab in other Microsoft 365 applications.

Prerequisites

To complete this tutorial, you'll need:

  • A Microsoft 365 Developer Program sandbox tenant
  • Your sandbox tenant enrolled in Office 365 Targeted Releases
  • A machine with Office apps installed from the Microsoft 365 Apps beta channel
  • (Optional) Teams Toolkit extension for Microsoft Visual Studio Code to help update your code

Prepare your personal tab for the upgrade

If you have an existing personal tab app, make a copy or a branch of your production project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID, for testing).

If you'd like to use sample code to complete this tutorial, follow the setup steps in the Todo List Sample to build a personal tab app using the Teams Toolkit extension for Visual Studio Code, then return to this article to update it for Microsoft 365.

Alternately, you can use a basic Single Sign-On hello world app already enabled Microsoft 365 in the following quickstart section and then skip to Sideload your app in Teams .

Quickstart

To start with a personal tab that's already enabled to run in Outlook and Office, use Teams Toolkit extension for Visual Studio Code.

  1. From Visual Studio Code, open the command palette (Ctrl+Shift+P), type Teams: Create a new Teams app.

  2. Select SSO enabled personal tab.

    Todo List sample (Works in Teams, Outlook and Office) in Teams Toolkit

  3. Select a location on your local machine for the workspace folder.

  4. Open the command palette (Ctrl+Shift+P) and type Teams: Provision in the cloud to create the required app resources (App Service plan, Storage account, Function App, Managed Identity) in your Azure account.

  5. Open the command palette (Ctrl+Shift+P) and type Teams: Deploy to the cloud to deploy the sample code to the provisioned resources in Azure and start the app.

From here, you can skip ahead to Sideload your app in Teams and preview your app in Outlook and Office. (The app manifest and TeamsJS API calls have already been updated for Microsoft 365.)

Update the app manifest

You'll need to use the Teams developer manifest schema version 1.13 to enable your Teams personal tab to run in Outlook and Office.

You have two options for updating your app manifest:

  1. Open the command palette: Ctrl+Shift+P.
  2. Run the Teams: Upgrade Teams manifest command and select your app manifest file. Changes will be made in place.

If you used Teams Toolkit to create your personal app, you can also use it to validate the changes to your manifest file and identify any errors. Open the command palette (Ctrl+Shift+P) and find Teams: Validate manifest file.

Update SDK references

To run in Outlook and Office, your app will need to reference the npm package @microsoft/teams-js@2.0.0 (or higher). While code with downlevel versions is supported in Outlook and Office, deprecation warnings are logged, and support for downlevel versions of TeamsJS in Outlook and Office will eventually cease.

You can use Teams Toolkit to help identify and automate the required code changes to upgrade from 1.x TeamsJS versions to TeamsJS version 2.0.0. Alternately, you can perform the same steps manually; refer to Microsoft Teams JavaScript client SDK for details.

  1. Open the Command palette: Ctrl+Shift+P.
  2. Run the command Teams: Upgrade Teams JS SDK and code references.

Upon completion, your package.json file will reference @microsoft/teams-js@2.0.0 (or higher) and your *.js/.ts and *.jsx/.tsx files will be updated with:

Important

Code inside .html files is not supported by the upgrade tooling and require manual changes.

Configure Content Security Policy headers

As in Microsoft Teams, tab applications are hosted within iframe elements in Office and Outlook web clients.

If your app makes use of Content Security Policy (CSP) headers, make sure you allow all the following frame-ancestors in your CSP headers:

Microsoft 365 host frame-ancestor permission
Teams teams.microsoft.com
Office *.office.com
Outlook outlook.office.com, outlook.office365.com, outlook-sdf.office.com, outlook-sdf.office365.com

Update Azure AD app registration for SSO

Azure Active Directory (AD) Single-sign on (SSO) for personal tabs works the same way in Office and Outlook as it does in Teams. However you'll need to add several client application identifiers to the Azure AD app registration of your tab app in your tenant's App registrations portal.

  1. Sign in to Microsoft Azure portal with your sandbox tenant account.

  2. Open the App registrations blade.

  3. Select the name of your personal tab application to open its app registration.

  4. Select Expose an API (under Manage).

    Authorize client Ids from the *App registrations* blade on Azure portal

  5. In the Authorized client applications section, ensure all of the following Client Id values are added:

    Microsoft 365 client application Client ID
    Teams desktop, mobile 1fec8e78-bce4-4aaf-ab1b-5451cc387264
    Teams web 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
    Office web 4765445b-32c6-49b0-83e6-1d93765276ca
    Office desktop 0ec893e0-5785-4de6-99da-4ed124e5296c
    Outlook desktop, mobile d3590ed6-52b3-4102-aeff-aad2292ab01c
    Outlook web bc59ab01-8403-45c6-8796-ac3ef710b3e3

Sideload your app in Teams

The final step to running your app in Office and Outlook is to sideload your updated personal tab app package in Microsoft Teams.

  1. Package your Teams application (manifest and app icons) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the Zip Teams metadata package option in the Deployment menu of Teams Toolkit.

    'Zip Teams metadata package' option in Teams Toolkit extension for Visual Studio Code

  2. Sign in to Teams with your sandbox tenant account, and toggle into Developer Preview mode. Select the ellipsis (...) menu by your user profile, then select: About > Developer preview.

    From Teams ellipses menu, open 'About', and select 'Developer Preview' option

  3. Select Apps to open the Manage your apps pane. Then select Publish an app.

    Open the 'Manage your apps' pane and select 'Publish an app'

  4. Choose Upload a custom app option and select your app package.

    'Upload a custom app' option in Teams

After it's sideloaded to Teams, your personal tab is available in Outlook and Office. Be sure to sign in with the same credentials you used to sign in to Teams to sideload your app.

You can pin the app for quick access, or you can find your app in the ellipses (...) flyout among recent applications in the sidebar on the left. Pinning an app in Teams don't pin it as an app in Office or Outlook.

Preview your personal tab in other Microsoft 365 experiences

Here's how to preview your app running in Office and Outlook, web and Windows desktop clients.

Note

Uninstalling your app from Teams also removes it from the More Apps catalogs in Outlook and Office. If you're using the Teams Toolkit sample app provided above.

Outlook on Windows

To view your app running in Outlook on Windows desktop:

  1. Launch Outlook and sign in using your dev tenant account.

  2. On the side bar, select More Apps. Your sideloaded app title appears among your installed apps.

  3. Select your app icon to launch your app in Outlook.

    Click on the ellipses ('More apps') option on the side bar of Outlook desktop client to see your installed personal tabs

Outlook on the web

To view your app in Outlook on the web:

  1. Navigate to Outlook on the web and sign in using your dev tenant account.

  2. Select the ellipses (...) on the side bar. Your sideloaded app title appears among your installed apps.

  3. Select your app icon to launch and preview your app running in Outlook on the web.

    Click on the ellipses ('More apps') option on the side bar of outlook.com to see your installed personal tabs

Office on Windows

To view your app running in Office on Windows desktop:

  1. Launch Office and sign in using your dev tenant account.

  2. Select the ellipses (...) on the side bar. Your sideloaded app title appears among your installed apps.

  3. Select your app icon to launch your app in Office.

    Click on the ellipses ('More apps') option on the side bar of Office desktop client to see your installed personal tabs

Office on the web

To preview your app running in Office on the web:

  1. Log into office.com with test tenant credentials.

  2. Select the Apps icon on the side bar. Your sideloaded app title appears among your installed apps.

  3. Select your app icon to launch your app in Office on the web.

    Click on the 'More apps' option on the side bar of office.com to see your installed personal tabs

Troubleshooting

Currently, a subset of Teams application types and capabilities are supported in Outlook and Office clients. This support expands over time.

Refer to Microsoft 365 support to check host support for various TeamsJS capabilities.

For an overall summary of Microsoft 365 host and platform support for Teams apps, see Extend Teams apps across Microsoft 365.

You can check for host support of a given capability at runtime by calling the isSupported() function on that capability (namespace), and adjusting app behavior as appropriate. This allows your app to light up UI and functionality in hosts that support it, and provide a graceful fallback experience in hosts that don't. For more information, see Differentiate your app experience.

Use the Microsoft Teams developer community channels to report issues and provide feedback.

Debugging

From Teams Toolkit, you can Debug (F5) your tab application running in Office and Outlook, in addition to Teams.

Choose from Teams, Outlook, and Office debug targets in Teams Toolkit

Upon first run of local debug to Office or Outlook, you'll be prompted to sign in to your Microsoft 365 tenant account and install a self-signed test certificate. You'll also be prompted to manually install Teams. Select Install in Teams to open a browser window and manually install your app. Then click on Continue to proceed to debug your app in Office/Outlook.

Toolkit dialog Teams install

Provide feedback and report any issues with the Teams Toolkit debugging experience at Microsoft Teams Framework (TeamsFx).

Code sample

Sample Name Description Node.js
Todo List Editable todo list with SSO built with React and Azure Functions. Works only in Teams (use this sample app to try the upgrade process described in this tutorial). View
Todo List (Microsoft 365) Editable todo list with SSO built with React and Azure Functions. Works in Teams, Outlook, Office. View
Image Editor (Microsoft 365) Create, edit, open, and save images using Microsoft Graph API. Works in Teams, Outlook, Office. View

Next step

Publish your app to be discoverable in Teams, Outlook, and Office: