Microsoft Teams¶
With a licence key that includes chat-apps (licence keys),
Waylight works with Microsoft Teams in two ways, both set up by your own
admins with your own Microsoft registrations
(ADR 0023). This needs a
server built with the ee features.
- Search from the command box (opt-in, below): type in the Teams message box and pick a service, bookmark or wiki page from Waylight.
- The start page as a tab: a tab with your instance's name and a button that opens the start page in the browser (below).
The tab¶
The tab shows your instance's name and a button that opens the start page in the browser, where people are signed in as usual. Signing in inside Teams is deliberately not offered: the session cookie stays strict, so no other site can make the browser send it along.
It works for an instance inside your network: the Teams client on each
person's device loads the page, so it only has to be reachable from there
over HTTPS with a certificate the device trusts. It needs PUBLIC_URL and
a licence key with chat-apps; without them /teams/tab answers 404.
Add a static tab to your Teams app package (the same package as the command box search, or one of its own):
"staticTabs": [{
"entityId": "start",
"name": "Start page",
"contentUrl": "https://home.example.org/teams/tab",
"websiteUrl": "https://home.example.org/",
"scopes": ["personal"]
}],
"validDomains": ["home.example.org"]
Only this page may be shown inside Teams, Outlook and the Microsoft 365
app; the rest of the instance still refuses to be framed. The page loads
Microsoft's Teams library (version 2.58.0) from res.cdn.office.net, pinned
with a Subresource Integrity hash, because Teams shows a tab only after that
library has started.
Search from the command box¶
This is the one chat feature that needs Microsoft to reach your instance over the internet. It is off unless you switch it on.
What becomes reachable¶
Only one route: POST /api/teams/messages. Make just that path reachable
from the internet, for example with a rule in your reverse proxy, and keep
the rest of the instance private. If you use ALLOWED_CIDRS, the route is
covered by it too; Microsoft's addresses change, so a proxy rule by path is
easier to keep right.
Every request must carry a token signed by Microsoft's Bot Connector for your bot. Waylight checks it before anything else happens: issuer, audience (your bot's app ID), validity with five minutes of clock skew, the signature against Microsoft's published keys (refreshed daily), the service address and that the key is endorsed for Teams. Anything else is answered with 403.
Set it up (admins)¶
- In the Azure portal, create an Azure Bot resource (single tenant is
fine) and note its Microsoft App ID. Set its messaging endpoint to
https://<your public address>/api/teams/messagesand add the Microsoft Teams channel. - Set the app ID on the server and restart:
TEAMS_BOT_APP_ID=00000000-0000-0000-0000-000000000000
Waylight needs no bot password: the answer goes back in the HTTP
response.
3. Create a Teams app package with a search command for that bot and upload
it in the Teams admin center. The relevant part of manifest.json:
"composeExtensions": [{
"botId": "00000000-0000-0000-0000-000000000000",
"commands": [{
"id": "search", "type": "query", "title": "Search the start page",
"parameters": [{ "name": "q", "title": "Search", "description": "Service, bookmark or wiki page" }]
}]
}]
How people use it¶
Everyone first connects their Microsoft 365 account under Settings → Connected accounts (connected accounts); that tells Waylight which member is behind a Teams user. Others get a short hint and no results.
Results are what that member could find on the start page: services, their bookmarks and those shared with them, wiki pages including team wikis. Teams waits five seconds; slower sources are left out of that answer. Nothing is stored.
Outbound requests¶
login.botframework.com for the signing keys (at most daily, and at most
every five minutes for an unknown key) and graph.microsoft.com/v1.0/me
to match connected accounts to Teams users.