Prerequisites

Ensure that you adhere to the following prerequisites while building your Teams personal and channel or group tab:

• Enable discovery of your tab pages in an iFrame by utilizing X-Frame-Options and Content-Security-Policy HTTP response headers.

• Ensure that all Teams app pages are hosted on HTTPS endpoints.

• Set Content Security Policy headers to allow Teams and any other host applications of your app:

  Microsoft 365 app host	frame-ancestor permission
  All hosts (New)	*.cloud.microsoft
  Teams	teams.microsoft.com, *.teams.microsoft.com
  Microsoft 365 app	*.microsoft365.com, *.office.com,
  Outlook	outlook.office.com, outlook.office365.com, outlook-sdf.office.com, outlook-sdf.office365.com

  Warning

  Microsoft's cloud services, including web versions of Teams, Outlook, and Microsoft 365 domains, are migrating to the *.cloud.microsoft domain. Perform the following steps before September 2024 to ensure your app continues to render on supported Microsoft 365 web client hosts:

  1. Update TeamsJS library to v.2.19.0 or later. For more information about the latest release of TeamsJS, see Microsoft Teams JavaScript client library.

  2. If you've defined Content Security Policy (CSP) headers for your app, update the frame-ancestors directive to include the *.cloud.microsoft domain. To ensure backward compatibility during the migration, retain the existing frame-ancestors values in your CSP headers. This approach ensures that your app continues to work across both existing and future Microsoft 365 host applications and minimizes the need for subsequent changes.

  Update the following domain in the frame-ancestors directive of your app's CSP headers:

  https://*.cloud.microsoft
  

  Note

  To host the other Teams or Microsoft 365 apps within your app, upgrade your app to a Microsoft 365 environment. If you manage the app running in the nested frame, you can update its code to initialize the SDK by specifying your domain. This allows your nested frame to act as a proxy to Teams.

• For Internet Explorer 11 compatibility, set X-Content-Security-Policy. Alternately, set header X-Frame-Options: ALLOW-FROM https://teams.microsoft.com/. This header is deprecated but most browsers still accept it.

• Sign-in pages don't render in iFrames as a safeguard against clickjacking. Your authentication logic needs to use a method other than redirect. For example, use token-based or cookie-based authentication.

  Note

  It is recommended that you set the intended use for your cookies rather than rely on default browser behavior. For more information, see SameSite cookie attribute.

• Browsers same-origin policy restriction prevents webpages from making requests to different domains than the served web page. So, you can redirect the configuration or content page to another domain or subdomain. Your cross-domain navigation logic needs to allow the Teams client to validate the origin against a static validDomains list in the app manifest when loading or communicating with the tab.

• Style your tabs based on the Teams client's theme, design, and intent. Tabs work best when built to address a specific need and focus on a small set of tasks or a subset of data that is relevant to the tab's channel location.

• Within your content page, add a reference to Microsoft Teams JavaScript client library using script tags. After your page loads, make a call to app.initialize(), or else your page isn't displayed.

• For authentication to work on mobile clients, you must upgrade to TeamsJS version 1.4.1 or later.

• If you choose to have your channel or group tab to appear on Teams mobile client, the setConfig() configuration must have a value for the websiteUrl property.

• Microsoft Teams tab doesn't support the ability to load intranet websites that use self-signed certificates.

Tools to build tabs

Build your Teams tab

Now let's build your tab. But first select your choice of tab to build:

See also

• Build tabs for Teams
• Build your first tab app using JavaScript
• Register your tab app in Microsoft Entra ID
• Tabs on mobile
• Grant tab device permission in Teams
• Content Security Policy