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 and Office desktop and web experiences, as well as Office app for Android.

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

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 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) An Android device or emulator with Office app for Android installed and enrolled in the beta program
  • (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 Create a new Teams app option.

  3. Select SSO enabled personal tab.

    The Screenshot is an example that shows the Todo List sample (Works in Teams, Outlook and Office) in Teams Toolkit.

  4. Select preferred programming language.

  5. Select a location on your local machine for the workspace folder and enter your application name.

  6. 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.

  7. Select a subscription and a resource group.

  8. Select Provision.

  9. 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.

  10. Select Deploy.

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.)

SharePoint Framework (SPFx) apps

Starting with version 1.16 of SharePoint Framework (SPFx), Teams personal tabs built and hosted with SPFx are also supported in Outlook and Office. To update a SPFx Teams personal tab app, follow these steps:

  1. Ensure you have the latest version of SPFx.

    npm install @microsoft/generator-sharepoint@latest --global
    
  2. Update the app manifest.

  3. Update the SDK references.

After you update the SDK references, sideload your app in Teams to preview your SPFx personal tab app running in Outlook and Office. For more information, see Extend Outlook and Office with the SharePoint Framework.

Update the app manifest

You 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 needs to refer the npm package @microsoft/teams-js@2.5.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 2.x.x versions. 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 *.microsoft365.com, *.office.com
Outlook outlook.live.com, 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 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).

    The screenshot is an example that shows the 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
    Office mobile d3590ed6-52b3-4102-aeff-aad2292ab01c
    Outlook desktop, mobile d3590ed6-52b3-4102-aeff-aad2292ab01c
    Outlook web bc59ab01-8403-45c6-8796-ac3ef710b3e3

    Note

    Some Microsoft 365 client applications share Client IDs.

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.

    'The screenshot is an example that shows the 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.

    The screenshot describes how to select 'Developer Preview' option.

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

    The screenshot is an example that shows the Manage your apps pane and Publish an app options.

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

    The screenshot is an example that shows the option to upload am app in Teams.

After it's sideloaded to Teams, your personal tab is available in Outlook and Office. You must sign in with the same credentials that you used to sideload your app into Teams. When running the Office app for Android, you need to restart the app to use your personal tab app from the Office 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 doesn'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

If you use the Teams Toolkit sample app and uninstall it from Teams, it is removed from the More Apps catalogs in Outlook and Office.

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.

    The screenshot is an example that shows 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. Go to Outlook on the web 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 and preview your app running in Outlook on the web.

    The screenshot is an example that shows 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 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.

    The screenshot is an example that shows 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.

    The screenshot is an example that shows the (More apps) option on the side bar of office.com to see your installed personal tabs.

Office app for Android

Note

Before installing the app, perform the steps to install the latest Office app beta build and be a part of the beta program.

To view your app running in Office app for Android:

  1. Launch the Office app and sign in using your dev tenant account. If the Office app for Android was already running prior to sideloading your app in Teams, you need to restart it in order to see in your installed apps.

  2. Select the Apps icon. Your sideloaded app appears among installed apps.

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

    The screenshot is an example that shows the 'Apps' option on the side bar of the Office app to see your installed personal tabs.

Troubleshooting

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

Tip

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.

The screenshot is an example that shows the dropdown menu of debug in Teams in the Teams Toolkit.

Upon first run of local debug in 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 select Continue to proceed to debug your app in Office/Outlook.

The screenshot is an example that shows the Toolkit dialog box to install in Teams.

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

Mobile debugging

Teams Toolkit (F5) debugging isn't yet supported with Office app for Android. Here's how to remotely debug your app running in Office app for Android:

  1. If you debug using a physical Android device, connect it to your dev machine and enable the option for USB debugging. This is enabled by default with the Android emulator.

  2. Launch the Office app From your Android device.

  3. Open your profile Me > Settings > Allow debugging, and toggle on the option for Enable remote debugging.

    The screenshot is an example that shows the Enable remote debugging toggle option.

  4. Leave Settings.

  5. Leave your profile screen.

  6. Select Apps and launch your sideloaded app to run within the Office app.

  7. Ensure your Android device is connected to your dev machine. From your dev machine, open your browser to its DevTools inspection page. For example, go to edge://inspect/#devices in Microsoft Edge to display a list of debug-enabled Android WebViews.

  8. Find the Microsoft Teams Tab with your tab URL and select inspect to start debugging your app with DevTools.

    The screenshot is an example that shows the list of webviews in devtool.

  9. Debug your tab app within the Android WebView. In the same way you remotely debug a regular website on an Android device.

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
Sample Launch Page (Microsoft 365) Demonstrates SSO authentication and TeamsJS SDK capabilities as available in different hosts. Works in Teams, Outlook, Office. View
Northwind Orders app Demonstrates how to use Microsoft TeamsJS SDK V2 to extend teams application to other Microsoft 365 host apps. Works in Teams, Outlook, Office. Optimized for mobile. View

Next step

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