Adding a WordPress tab to Microsoft Teams and use Single Sign-on

Use this guide if you want to add a new (personal) tab to Microsoft Teams that loads (a page from) your WordPress intranet / website and expect users to be signed in automatically (SSO) with their Office 365 / Azure AD work or school account with the help of the WordPress + Office 365 plugin.

Before you start

  • You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
  • You are an Administrator for your WordPress website.
  • You have installed the WPO365 | SAMESITE plugin. See the paragraph "WPO365 | SAMESITE" at the end of this article for additional background information on this topic.

Choose your Single Sign-on

Starting with WPO365 | LOGIN version 16 that was released early December 2021 the WPO365 plugin offers a seamless single sign-on experience for Teams Tabs that embed a WordPress website that requires a user to sign in with their work, school or Microsoft account. This article has been updated to reflect these changes and offers guidance to implement Single Sign-on support for Teams Tabs using one of the following alternatives.

  • Single Sign-on (recommended) The WPO365 plugin will acquire with the help of the Microsoft Teams SDK an ID token on behalf of the logged-in user and will use it to sign in the user in WordPress. 
  • Integrated The WPO365 will try to launch a popup window for the user to sign in with Microsoft and if the user did so successfully sign in the user in WordPress.

It is recommended that administrators that already used the WPO365 | LOGIN prior to version 16 to authenticate users that access their WordPress website via a Teams Tab review their Integrated implementation and update it to the recommended Single Sign-on implementation.

Option 1: Seamless Single Sign-on support for Tabs (recommended)

Please note  For the WPO365 plugin to be able to acquire an ID token with the help of the Microsoft Teams SDK you must package your Microsoft Teams Tab that embeds your WordPress website in a Teams App. A Teams App includes a so-called manifest that contains important information such as the Application ID and Application ID URI (= Resource URL) that the Microsoft Teams SDK needs when it tries to acquire an auth token for SSO.

Perform the following steps to build a simple proof-of-concept Microsoft Teams App with a Tab that embeds a WordPress website that requires a user to sign in with their work, school or Microsoft account.

Prepare your App registration

For the Microsoft Teams SDK to be able to acquire an auth token on behalf of the logged-in user, you must register your (WordPress website as an) application in Azure Active Directory. When you are reading this article then it is very likely that you already created an App registration  for your WordPress website to enable Microsoft based Single Sign-on for WordPress with the help of the WPO365 | LOGIN plugin. If you have not done so already, then please do it now by following the steps explained in this Getting started guide.

Apply the following changes to your App registration to support seamless single sign-on for Microsoft Teams Tabs that embed a WordPress website.

  • Navigate to WP Admin > WPO365 > Single Sign-on and click the link View in Azure Portal for the Application ID. This will open your Azure AD App registration in Azure Portal.
  • Under Manage, select Expose an API.
  • Select the Set link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name with a forward slash "/" appended to the end, between the double forward slashes and the GUID. The entire ID must have the form of api://fully-qualified-domain-name.com/{AppID}. ² For example, api://subdomain.example.com/00000000-0000-0000-0000-000000000000. The fully qualified domain name is the human readable domain name from which your app is served. If you're using a tunneling service such as ngrok, you must update this value whenever your ngrok subdomain changes.
  • Select Add a scope. In the panel that opens, enter access_as_user as the Scope name.
  • In the Who can consent? box, enter Admins and users.
  • Enter the details in the boxes for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope:
    • Admin consent title: Teams can access the user’s profile.
    • Admin consent description: Teams can call the app’s web APIs as the current user.
    • User consent title: Teams can access your profile and make requests on your behalf.
    • User consent description: Teams can call this app’s APIs with the same rights as you have.
  • Ensure that State is set to Enabled.
  • Select Add scope to save the details. The domain part of the Scope name displayed below the text field must automatically match the Application ID URI set in the previous step, with /access_as_user appended to the end api://subdomain.example.com/00000000-0000-0000-0000-000000000000/access_as_user.
  • In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 for Teams mobile or desktop application.
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 for Teams web application.
Please note The fully qualified domain name must correspond to your WordPress website's web address and this domain name must have been added (and verified) as a custom domain to Azure AD. If your website's web address is https://www.example.com/ then you must have added example.com as a custom domain to Azure AD and your Application ID URI must be api://www.example.com/{AppID}. 

Further reading:

Last but not least If you are not able or you do not wish to apply this configuration to your App registration in Azure AD then you can still benefit from a deeply integrated but less seamless single sign-on experience. If the Microsoft Teams SDK is not able to acquire an auth token on behalf of the logged-in user then the WPO365 plugin will automatically fallback to Option 2: Integrated Single Sign-on support for Tabs. In that case you can skip the app's Domains and permissions configuration page and leave the fields AAD App ID and Single Sign-on empty.
Build a custom Microsoft Teams App
Please note The  App Studio app will soon be deprecated and this documentation will be updated in the beginning of 2022 to reflect this change. 

Also note that th e desktop and mobile apps' built-in browser aggressively caches tab content. Therefore you may find it easier to develop and test your app with Microsoft Team's browser app first before you give it a go with a different app. Also see the paragraph "Empty cache" at the end of this article for tips how to clear the cache of the desktop app. 
  • In the Teams App (browser or desktop) click the 3-dot ... menu item and search for the App Studio app provided by Microsoft and install it.
  • Open App Studio.
  • Select Manifest Editor.
  • Click + Create a new app.
  • Complete the App Details.
    • Short name e.g. "SSO"
    • Full name e.g. "Single Sign-on"
    • App ID e.g. "e2d890b6-1ec4-4d85-92ef-46de67b722ac"  (click to generate)
    • Package name e.g. "com.wpo365.sso"
    • Version e.g. "1.0.0" (make sure to increase the version each time you change your app)
    • Short description e.g. "..."
    • Full description e.g. "..."
    • Developer e.g. "Downloads by van Wieren"
    • Website e.g. "https://www.wpo365.com/"
    • Privacy statement e.g. "https://www.wpo365.com/privacy/"
    • Terms of use e.g. "https://www.wpo365.com/terms/"
  • Complete Capabilities > Tabs
    • Click to Add a personal tab.
    • Name e.g "WordPress Teams Tab"
    • Entity ID e.g. "WpTeamsTab"
    • Content URL e.g. "https://wpo365connect.com/"
  • Complete Finish > Domains and permissions
    • Verify that under Domains from your tabs your domain has been added e.g. "wpo365connect.com"
    • AAD App ID e.g. "00000000-0000-0000-0000-000000000000" (must be the ID of the application that you registered in Azure AD)
    • Single Sign-on e.g. "api://connectwpo365.com/00000000-0000-0000-0000-000000000000" (must be the App ID URI of the application that you registered in Azure AD)
  • Review Finish > App Manifest
    • Review your App's manifest and especially ensure that a webApplicationInfo section with your App registration's application ID and application ID URI has been added.
  • Install Finish > Test and distribute
    • Click to Install and test your new custom app in Teams.

Option 2: Integrated Single Sign-on support for Tabs

By far the easiest way to embed your WordPress website in a Microsoft Teams Tab would be by manually adding a new Website app and configure its URL to the address of your WordPress website.

  • Launch the Microsoft Teams app (browser or desktop).
  • Navigate to the Team of your choice and select the Channel where you would like to add a tab that displays information from your WordPress website that requires users to Sign in with Microsoft.
  • From the top navigation click + to add a new Tab.
  • From the Tabs for your team section select Website.
  • Enter a Name for your Tab e.g. WordPress website.
  • Enter the URL of your WordPress website.
  • Click Save.

When a user now clicks the newly added Tab, he / she will be automatically signed in as follows:

  • First the WPO365 loading template is visible and the WPO365 plugin initializes its Single sign-on capability.
  • Then a popup appears and either closes immediately automatically or the user must select his / her login account when there are multiple accounts to choose from.
  • And finally - once the popup is closed - the Tab's content page is rendering the content from your WordPress website that requires users to Sign in with Microsoft.
Known limitations
  • Some plugin capabilities e.g. Dual login may not work as expected when the WordPress website is loaded inside a (personal) Teams Tab.
  • Teams may prevent some pages from loading correctly because of limitations that apply to loading content in iframes.
  • When visiting https://teams.microsoft.com with a Safari browser, the popup renders as a new browser tab. This may be caused by an issue that maybe resolved in a future release of the Microsoft Teams (JavaScript) SDK.
  • Please provide feedback if you experience any unexpected behavior.

WPO365 | SAMESITE

It is recommended to install the WPO365 | SAMESITE plugin. It will override the pluggable WordPress function wp_set_auth_cookie to always set SameSite=None to enable third-party usage of cookies. Without setting SameSite=None modern browsers may fail to sign in the user.

Begin 2020 Chrome launched with new default settings for the SameSite cookie attribute. These changes may dramatically impact third-party cookie tracking, loosely akin to Safari's ITP. Previously, when the SameSite cookie attribute was omitted, browsers would share cookies with no domain limitations and thus third-party cookies could fire (is SameSite=None). Nowadays, more and more browsers only share cookies without a SameSite attribute when the domain in URL bar equals the cookie’s domain (first-party, is SameSite=Lax).

Basically this means that loading your WordPress site as an App or a Tab in Microsoft Teams in a browser is still possible as long as you do not require your users to sign in to view (private) pages and posts. If you do require users to sign in (e.g. with Microsoft with the help of one of the WPO365 plugins), however, then you may notice that this is impossible because the WordPress authentication cookies are by default no longer included by the browser. As a result the user is caught in an endless loop and bounces between your website and Microsoft's authentication endpoint login.microsoftonline.com.

Perform the following steps to install the plugin:

  • Go to WP Admin > Plugins > Add new and search for WPO365.
  • Click Install to install the WPO365 | SAMESITE plugin.
  • Click Activate to activate the plugin.
Please note Safari users go to  Preferences > Privacy and uncheck the option  Prevent cross-site tracking or else authentication in an iframe / popup will fail.

Empty Cache

When you develop an App with the App Studio and you made changes to your WordPress website you will notice that Microsoft Teams has aggressively cached your WordPress website. Perform the following steps to empty the cache.

  • Uninstall your App.
  • Quit Microsoft Teams (not only close / minimize it).
  • Open Windows Explorer and type %appdata% to open the AppData\Roaming folder.
  • Double-click the Microsoft folder to open it.
  • Double-click the Teams folder to open it.
  • Double-click the Cache folder to open it.
  • Delete its contents.
  • Start Microsoft Teams again.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us