Extend a Teams personal tab across Microsoft 365

Note

Extending a Teams personal tab across Microsoft 365 is currently available only in public developer preview. Features included in preview may not be complete, and may undergo changes before becoming available in the public release. They are provided for testing and exploration purposes only. They should not be used in production applications.

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 Microsoft Office Home (office.com).

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

  • Update your app manifest
  • Update your TeamsJS SDK references
  • Amend your Content Security Policy headers
  • Update your AAD App Registration for Single Sign On (SSO)

Testing your app will require the following steps:

  • Enroll your M365 tenant in Office 365 Targeted Releases
  • Configure your account to access preview versions of Outlook and Office apps
  • Sideload your updated app into Teams

After these steps, your app should appear in the preview versions of Outlook and Office apps.

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

If you'd like to use sample code to complete this tutorial, follow the setup steps in Getting Started with Todo List Sample to build a personal tab app using the Teams Toolkit extension for Visual Studio Code. Or, you can start with the same Todo List Sample updated for TeamsJS SDK v2 Preview and proceed to Preview your personal tab in other Microsoft 365 experiences. The updated sample is also available within Teams Toolkit extension: Development > View samples > Todo List (Works in Teams, Outlook and Office).

{alt-text}

Update the app manifest

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

You can either use Teams Toolkit to update your app manifest, or apply the changes manually:

  1. Open the Command palette: Ctrl+Shift+P
  2. Run the Teams: Upgrade Teams manifest to support Outlook and Office apps 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 or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code).

Teams Toolkit 'Validate manifest file' option under 'Deployment' menu

Update SDK references

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

You can use Teams Toolkit to help automate some of the code changes to adopt the next version of @microsoft/teams-js, but if you would like to do the steps manually, see Microsoft Teams JavaScript client SDK Preview for details.

  1. Open the Command palette: Ctrl+Shift+P
  2. Run the command Teams: Upgrade Teams JS SDK references to support Outlook and Office apps

Upon completion, the utility will have updated your package.json file with the TeamsJS SDK Preview (@microsoft/teams-js@2.0.0-beta.1) dependency, 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 will require manual changes.

Note

If you wish to manually update your code, see Microsoft Teams JavaScript client SDK Preview to learn about the required changes.

Configure Content Security Policy headers

Just 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 are allowing all of 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

Update AAD app registration for SSO

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

  1. Sign in to 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

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.com 4345a7b9-9a63-4910-a426-35363201d503
Office.com 4765445b-32c6-49b0-83e6-1d93765276ca
Office desktop 0ec893e0-5785-4de6-99da-4ed124e5296c
Outlook desktop d3590ed6-52b3-4102-aeff-aad2292ab01c
Outlook Web Access 00000002-0000-0ff1-ce00-000000000000
Outlook Web Access bc59ab01-8403-45c6-8796-ac3ef710b3e3

Sideload your app in Teams

The final step is to sideload your updated personal tab (app package) in Microsoft Teams. Once completed, your app will be available to run in Office and Outlook, in addition to 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 or in the Command Palette Ctrl+Shift+P of Visual Studio Code:

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

  2. Log in to Teams with your sandbox tenant account, and ensure that you are on the Public Developer Preview. You can verify that you're on the Preview in the Teams client by clicking on the ellipsis (...) menu by your user profile and opening About to check that the Developer preview option is toggled on.

    From Teams ellipses menu, open 'About' and verify 'Developer Preview' option is checked

  3. Open the Apps pane, and click Upload a custom app and then Upload for me or my teams.

    'Upload a custom app' button in the Teams 'Apps' pane

  4. Select your app package and click Open.

Once sideloaded through Teams, your personal tab will be available in Outlook and Office. Be sure to sign in with the same credentials you used to sideload your app in Teams.

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.

Note

Pinning an app in Teams will not pin it as an app in Office.com or Outlook.

Preview your personal tab in other Microsoft 365 experiences

When you upgrade your Teams personal tab and sideload it in Teams, it will also run in Outlook desktop and web clients and Microsoft Office Home (office.com). Here's how to preview it from those Microsoft 365 experiences.

Outlook

To view your app running in Outlook on Windows desktop, launch Outlook and sign in using your dev tenant account. Click on the ellipses (...) on the side bar. Your sideloaded app title will appear among your installed apps.

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

Click on your app icon to launch your app in Outlook.

Outlook on the web

To view your app in Outlook on the web, visit https://outlook.office.com and sign in using your dev tenant account. Click on the ellipses (...) on the side bar. Your sideloaded app title will appear among your installed apps.

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

Microsoft Office Home

To preview your app running in Microsoft Office Home, log into office.com with test tenant credentials. Click on the ellipses (...) on the side bar. Your sideloaded app title will appear among your installed apps.

Click on your app icon to launch your app in Office Home.

Next steps

Outlook- and Office-enabled personal tabs are in preview and are not supported for production use. Here's how to distribute your personal tab app to preview audiences for testing purposes.

Single-tenant distribution

Outlook- and Office-enabled personal tabs can be distributed to a preview audience across a test (or production) tenant in one of three ways:

Teams client

From the Apps menu, select Manage your apps > Submit an app to your org. This requires approval from your IT admin.

Microsoft Teams Admin Center

As a Teams admin, you can upload and pre-install the app package for your organization's tenant from https://admin.teams.microsoft.com/. See Upload your custom apps in the Microsoft Teams admin center for details.

Microsoft Admin Center

As a global admin, you can upload and pre-install the app package from https://admin.microsoft.com/. See Test and deploy Microsoft 365 Apps by partners in the Integrated apps portal for details.

Multi-tenant distribution

Distribution to Microsoft AppSource is not supported during this early developer preview of Outlook- and Office-enabled Teams personal tabs.