The workplace app can run as a personal tab in Microsoft Teams, Outlook and the Microsoft 365 app. The app package in apps/workplace/teams/ adds the tab. The tab loads the workplace app from the PlaceOS host.
- The tab URL has the query
?host=teams. Without this query, the app starts as a normal web app. - With the query, the app loads
@microsoft/teams-jsand callsapp.initialize(). If the host does not answer in 5 seconds, the app starts as a normal web app. - The tab frame cannot show the Microsoft login page. Thus the app does not redirect to the PlaceOS login page in the tab.
- If the tab has no PlaceOS token, the app gets a token in this sequence:
- Single sign-on (SSO) with
authentication.getAuthToken(). ts-client exchanges the Microsoft Entra token for PlaceOS tokens (RFC 8693 token exchange). - A sign-in window from
authentication.authenticate(). This window loads the app with?host=teams-authand runs the normal PlaceOS login. Then it sends the PlaceOS token to the tab. - If a host blocks the sign-in window, the tab shows a Sign in button. The user selects the button to open the window again.
- Single sign-on (SSO) with
The code is in libs/common/src/lib/teams-host.ts. PlaceOS_Service.init() calls it. The Sign in button is in apps/workplace/src/app/app.component.ts.
Run this command from the repository root:
bun apps/workplace/teams/package.ts --host example.placeos.com --app-id <app-guid> --client-id <client-guid>| Option | Description |
|---|---|
--host |
Host name of the PlaceOS server. Do not include the protocol or a path. |
--app-id |
Teams app ID. Make a new GUID for each package. Keep the same GUID for updates to the same package. |
--client-id |
Optional. Client ID of the Microsoft Entra app for SSO. Without it, the tab always uses the sign-in window. |
--path |
Optional. Path of the workplace app on the host. The default is /workplace/. |
--out |
Optional. Output folder. The default is dist/teams. |
The script writes the package to dist/teams/workplace-<host>.zip. The script uses the zip command.
The template is apps/workplace/teams/manifest.json. It uses app manifest schema 1.30. Microsoft 365 hosts need schema 1.13 or later.
Do these steps only if you use SSO.
-
In the Azure portal, open App registrations and create a registration.
-
Open Expose an API.
-
Set the Application ID URI to
api://<host>/<client-id>. -
Add the scope
access_as_user. Let admins and users give consent. -
In Authorized client applications, add all of these client IDs with the
access_as_userscope:Client application Client ID Teams desktop, mobile 1fec8e78-bce4-4aaf-ab1b-5451cc387264Teams web 5e3ce6c0-2b1f-4285-8d4b-75ee78787346Microsoft 365 web 4765445b-32c6-49b0-83e6-1d93765276caMicrosoft 365 desktop 0ec893e0-5785-4de6-99da-4ed124e5296cMicrosoft 365 mobile, Outlook desktop d3590ed6-52b3-4102-aeff-aad2292ab01cOutlook web bc59ab01-8403-45c6-8796-ac3ef710b3e3Outlook mobile 27922004-5251-4030-b22d-91ecd9a37ea4 -
Use the application (client) ID as
--client-id.
The Outlook add-in can use the same app registration for single sign-on. It needs one more redirect URI. See Outlook add-in.
The source of the client IDs is Extend a Teams personal tab across Microsoft 365.
Note: The PlaceOS backend must accept token exchange for Microsoft Entra tokens from this app registration. The aud claim of the token is the client ID or the Application ID URI. If the backend refuses the exchange, the tab uses the sign-in window. In this condition, build the package without --client-id.
The hosts show the tab in a frame. The PlaceOS host must let these hosts frame the workplace app.
- Remove the
X-Frame-Optionsheader from the workplace app responses, or do not set it toDENYorSAMEORIGIN. - Add these values to the
frame-ancestorsdirective of theContent-Security-Policyheader:
Content-Security-Policy: frame-ancestors 'self' https://*.cloud.microsoft https://teams.microsoft.com https://*.teams.microsoft.com https://*.microsoft365.com https://*.office.com https://outlook.office.com https://outlook.office365.com https://outlook-sdf.office.com https://outlook-sdf.office365.comMicrosoft moves its web hosts to *.cloud.microsoft. Keep all of the values.
- In the Teams admin center, open Teams apps > Manage apps.
- Select Upload new app and upload the package.
- Make sure that the app permission policies allow the app.
- To pin the app in Teams, open Teams apps > Setup policies. Add the app to Pinned apps, then assign the policy to users.
The app is then also available in Outlook and the Microsoft 365 app, in More apps. A pin in Teams does not pin the app in Outlook or the Microsoft 365 app. You can also deploy the app from the Microsoft 365 admin center, in Settings > Integrated apps.
For a test, a user can upload the package in Teams from Apps > Manage your apps > Upload an app.
- Token expiry: With SSO, ts-client uses the refresh token from the exchange to get a new PlaceOS token. The app does not refresh a token from the sign-in window. When that token expires, API requests fail. Reload the tab to sign in again.
- Sign out: Sign out goes to the PlaceOS logout page in the tab frame. This can fail in the frame.
- External links:
libs/components/src/lib/user-controls.component.tsandlibs/explore/src/lib/explore-spaces.service.tsusewindow.open(). Web hosts usually open a new browser tab. Desktop and mobile hosts are not validated. A follow-up can useapp.openLink()from teams-js in the host. - Classic Outlook for Windows: Support for Microsoft 365 personal tabs in classic Outlook is not validated.
- Storage: In web hosts, the browser can partition the storage of the tab frame. The tab keeps its own copy of the token. Thus a sign-in in a normal browser tab does not sign in the Teams tab.