Approvals in Teams and on your phone
Sign a plain gate from a Microsoft Teams card through your company's own bot, get a Web Push on your phone when a gate waits, and sign on a phone-first screen — through the same checks as the console.
Two more places to sign from, both on top of Notifications, Slack and Teams:
- Microsoft Teams bot — your company's own Azure Bot sends each person who may sign a card in their 1:1 chat with it. A plain gate is approved or refused on the card.
- Your phone — Minctrl installs on the home screen (a PWA), sends a Web Push when a gate
waits, and opens a phone-first sign-off screen at
/m/signoff.
Both go through the one sign door — the same function the console calls — so role,
separation of duties, N-of-M approvals, gate forms and the typed confirmation of a live
irreversible action hold exactly as they do on the desktop. Every signature made from a Teams card
is recorded in the audit chain with channel: "teams".
A Teams card signs only what Slack may sign. A gate is signable from chat when it has no form, one signature clears it, it is not a shadow test run, and none of its outcomes authorizes a live irreversible action (or connectors that could not be read). Anything else gets one Open in Minctrl button. The phone screen is the console: forms and the typed confirmation work there.
The Teams bot
What your Microsoft admin does (the owner's step, once)
Minctrl never registers anything in your tenant; this part is yours.
- Azure portal → Create a resource → Azure Bot. Type of app: Single Tenant. Creation type: Create new Microsoft App ID. Note the Microsoft App ID and the tenant (directory) ID shown on the bot's Configuration page.
- On the bot's Configuration page set Messaging endpoint to the URL Minctrl shows on
Settings → Notifications → Microsoft Teams bot — it is
https://<your Minctrl host>/api/integrations/teams/messages. - Open the app registration (Manage Password link) → Certificates & secrets → New client secret. Copy the secret value (it is shown once).
- On the bot: Channels → Microsoft Teams → Apply (commercial cloud).
What a Minctrl owner or admin does
- Settings → Notifications → Microsoft Teams bot: paste the App ID, the client secret and
the tenant ID, Connect the bot. Minctrl fetches a Bot Framework token with them first —
a wrong secret or tenant is refused here (
invalid_client, …) and nothing is stored. The secret is stored encrypted and never shown again; the change is in the audit chain (notifications_changed,what: teams_bot). - Download the Teams app package (
manifest.jsonwith your App ID, and two icons) and upload it: Teams admin center → Teams apps → Manage apps → Upload new app, or for a pilot, Teams → Apps → Manage your apps → Upload a custom app. Replace the placeholder icons with your own if you like (192×192 colour, 32×32 white outline). - Ask the signers to open Minctrl in Teams and say hello. The bot answers "You are connected" — or, when no active member of your company has their work email, says so.
Pause stops new cards without forgetting anything; Remove forgets the secret and every conversation, and cards already sent can no longer sign.
Who gets a card, and how they are matched
A card goes to the same people email and Slack would tell — whoever may sign the gate — who have opened the bot: the bot can only write to a person who installed it or wrote to it. When they do, Minctrl stores the 1:1 conversation and asks Microsoft (the conversation's member list, with the bot's own token) for that person's email, else their UPN. That address is matched to a member of your company. It is asked again on every press of a card, so a person whose account changed since is not signed in as someone else.
Each person turns Teams on or off for themselves under Your notifications, and the company sets the default for people who chose nothing.
The card
The card says what waits, the run, how long it has waited and its deadline. When the gate is signable from chat and the person may sign it: Approve (or each outcome of a multi-outcome gate) and Deny…, which opens a required Reason field — the reason is recorded with the signature. Otherwise only Open in Minctrl, and the card says why.
After a press the card is replaced by the outcome ("Approved by … from Teams — the run completed"). Every other signer's card is refreshed to "Signed by … — nothing more to do", and a card opened later refreshes itself to the current state. A refusal (separation of duties, a role that may not sign, a gate that changed since the card was sent) is shown on the card and nothing is signed.
How Minctrl checks what Teams sends
Every request to /integrations/teams/messages carries a token from the Bot Framework. Minctrl
accepts it only when it is RS256, signed by a key from the Bot Framework's OpenID metadata
(cached, refreshed when a new key appears), issued by https://api.botframework.com, for
audience = your App ID, not expired (5 minutes of clock skew), and naming the same
serviceUrl as the activity. Then: the activity's tenant must be yours (403 otherwise), and each
activity id is accepted once (409 for a replay). Minctrl only ever calls Bot Framework hosts
back (smba.trafficmanager.net, *.botframework.com).
| Answer | Means |
|---|---|
401 | no token, not signed by the Bot Framework, expired, or for a bot Minctrl does not know |
403 | another Microsoft tenant |
404 | your company's bot is paused |
409 | this activity was already received |
The incoming-webhook Teams channels of Notifications stay as they were: a link card per channel, for companies without a bot.
Your phone
Install
Open Minctrl in the phone's browser and Add to Home Screen (Safari: Share → Add to Home Screen; Chrome: ⋮ → Install app). It opens straight on the sign-off screen. On an iPhone, Web Push works only for the installed app (iOS 16.4 and later).
Push notices
On /m/signoff (or Settings → Notifications → Your devices) press Turn on / Get
push notices on this device and allow notifications. Each device is listed with when it was last
reached; Remove stops it, Send a test push checks it.
A push says only how many gates wait — "1 gate waits for you" — and links to /m/signoff. No
process, step, person, amount or any other content of the run: a lock screen shows it to anyone
holding the phone. Several gates due at once make one push with the count.
How it works: the installation has one VAPID key pair (made on first use, the private half
stored encrypted). Each push is encrypted for that one device (RFC 8291, aes128gcm, with the
device's own key and auth secret, also stored encrypted) and signed with a short-lived VAPID token
(RFC 8292). Minctrl posts only to known push services (Google FCM, Mozilla, Microsoft WNS, Apple);
a device the push service no longer knows (404 / 410) is removed at once. A push service that
is down is retried with backoff like any other notice; each delivery is on the run's
Notifications panel as channel Push.
Push is on for everyone who subscribed a device unless they turn it off under Your notifications; the company can set the default.
Signing on the phone
/m/signoff lists the gates that wait for you, soonest deadline first, as large rows; a tap opens
one gate: what it authorizes, every outcome as a large button, the gate's form, a note (a
refusal's reason) and one Sign button in reach of the thumb. A live irreversible action asks
for its gate id typed, exactly as on the desktop. The screen is designed for 375 px and never
scrolls sideways.
Nothing is kept for offline use. The service worker caches only an offline page and the app icons; every page and every API call goes to the network. Without a connection the app shows Not connected — never a stale queue someone could sign from.
Configuration (self-hosting)
| Variable | Default | What it is for |
|---|---|---|
TEAMS_MESSAGING_BASE | <APP_URL>/api | the base of the messaging endpoint shown on Settings |
PUSH_VAPID_SUBJECT | mailto:[email protected] | the contact push services see in the VAPID token |
TEAMS_BOT_OPENID_URL, TEAMS_LOGIN_BASE, TEAMS_SERVICE_URL_ORIGINS, PUSH_ALLOWED_ORIGINS | Microsoft's / none | test and local-stack overrides only (the browser suite points them at mocks) |
Limits
- Registering the Azure Bot and uploading the app to your tenant is your Microsoft admin's step; Minctrl is tested against a Bot Framework mock, not your tenant.
- The bot writes only to people who opened it; others are told by email, Slack or push.
- Group chats and channels are not supported by the bot — cards go to 1:1 chats only.
Notifications, Slack and Teams
Tell the people who may sign a gate that it waits — by email, Slack or Microsoft Teams — and let them sign a plain gate from the Slack message, through the same checks as the console.
Run a governed process
Start a run of a process saved in your company, understand why it parks, resume it on the right gate, and keep irreversible tools shadowed.