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 have selected the Intranet authentication scenario (on the plugin's Single Sign-on configuration page) or have at least defined a couple of WordPress front-end posts or pages as private (using Audiences or by adding those posts or pages to the Private pages list). Otherwise, your WordPress pages are available to anyone and there would be no need to implement seamless SSO.
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.

Seamless Single Sign-on support for Tabs

Please note In order for your users to be signed in automatically (SSO) with their Office 365 / Azure AD work or school account when you integrate your WordPress Website into Microsoft Teams, you must create a Microsoft Teams App. Such 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 your WordPress website, that requires a user to sign in with their work, school or Microsoft account.

Step 1 - Prepare your (Azure AD) 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 in Azure AD 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.

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. In this example, the website is hosted at https://www.wpo365connect.com/ and this domain has been added to Azure AD (on the Custom domain names page) . The Application ID URI therefore is as shown below.

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.

Step 2 - Build a custom Microsoft Teams App

Please note Th e Microsoft Teams 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 Developer Portal app provided by Microsoft and install it.

Open Developer Portal.
Click + New app, enter a name e.g. WPO365 Connect and click Add.

Complete the Basic information.
- Short name e.g. "WPO365 Connect"
- Full name e.g. "WPO365 Connect for Teams"
- App ID (will be generated for you)
- Short description e.g. "WPO365 Connect: Your WordPress based Teams app"
- Full description e.g. "WPO365 Connect: Your WordPress based Teams app with support for seamless SSO"
- Version e.g. "1.0.0" (make sure to increase the version each time you change your app)
- 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/"
- Application (client) ID* e.g. d567818c-64ef-4d34-b56d-e14697c413ad (this must be the ID of the Azure AD App registration that you updated before and for which you set the Application ID URI)

Click Save to persist the basic information.

Ensure on the Configure > Branding page that default icons have been selected. Only start changing the icons after you have successfully tested the seamless Single Sign-on SSO experience.
Click Configure > App features > Personal app to add a personal app, e.g. an app tab.
- Click to Create your first personal app tab.
- Name e.g "WordPress Teams Tab"
- Entity ID (will be generated for you)
- Content URL e.g. "https://www.wpo365connect.com/teams-tab/"
- Website URL e.g. "https://www.wpo365connect.com/"
- Scope e.g. personal
- Context e.g. personalTab
- Click Confirm to save your changes
- And finally click Save to add your personal tab.

Complete Configure > Single Sign-on
- Application ID URI* e.g. "api://www.wpo365connect.com/d567818c-64ef-4d34-b56d-e14697c413ad" (must be the Application ID URI that you set before)
- Click Save to keep your changes
Review Publish > App package > 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.

Step 3 - Publish your App (to your organization)

To enjoy the benefits of your new Teams App, you must publish it to your organization and approve it. There are many ways to achieve this. The following steps are therefore to be tailored for your organization and probably require alignment with your company's Teams admininstrator.

Perform the following steps to publish and approve your new Teams App tab.

Click Publish > Publish to org and finally Publish your app

Then continue to https://admin.teams.microsoft.com/policies/manage-apps (you must be a Teams administrator to be able to access this page and to approve your app for your organization).
On the Manage apps page you can now search for the new Teams app that you just submitted.

Now you can click the name of your app to open its About page and to Publish it.

After you published your Teams app, you will see a banner informing you that it ... may take a few hours before the status will be updated.
After you waited a few hours, return to Microsoft Teams (either in the browser or in the Teams App) and in the sidebar, click the 3-dot ... menu item and search for your Teams app by its name. When you find it, click its icon to Install it.
Before you click the app and see the magic in action, you should continue to step 4 and install the WPO365 | SAMESITE plugin, because without Without setting SameSite=None, modern browsers may fail to sign in the user.

Step 4 - 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.

Trouble shoot

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.

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.