Microsoft setup
Manual, one time, and it needs tenant admin rights. Nothing in the receiver can be deployed against a live channel until it is done. All of it is free: the Azure subscription costs nothing to create and the bot runs on the F0 tier.
1. Azure subscription
Section titled “1. Azure subscription”In the Azure portal, create a pay-as-you-go subscription on your Microsoft 365 tenant if one does not already exist. It is required only because the Azure Bot resource must live in a subscription.
2. Entra app registration
Section titled “2. Entra app registration”Entra ID → App registrations → New registration.
- Name: anything recognisable, for example
Sentinel - Supported account types: Accounts in this organizational directory only (single tenant)
- Redirect URI: none
Record the Application (client) ID and the Directory (tenant) ID.
Certificates & secrets → New client secret. Record the secret value (not the id) once; it is never shown again.
3. Store the secret
Section titled “3. Store the secret”BOT_CLIENT_SECRET='<the value>' \SENTRY_WEBHOOK_SECRET='<from the Sentry setup>' \SENTRY_API_TOKEN='<from the Sentry setup>' \ scripts/put-parameters.shThis writes /sentinel/bot-client-secret and the two Sentry parameters as
SecureStrings in the AWS account you are deploying into. The two Sentry values come
from Sentry setup; you can run this once with all three or
re-run it later.
4. Azure Bot resource
Section titled “4. Azure Bot resource”Azure portal → Create a resource → Azure Bot.
- Bot handle: your choice, but pick carefully. It is immutable in Azure, while the display name can be changed later.
- Pricing tier: F0 (free)
- Type of App: Single Tenant
- Creation type: Use existing app registration, with the client id and tenant id from step 2
After creation, Settings → Configuration → Messaging endpoint: <FunctionUrl>bot, the
stack output from the deploy with bot appended.
Then Channels → Microsoft Teams → enable.
5. Fill in the config
Section titled “5. Fill in the config”In config/receiver.yaml, replace:
teams.tenant_idwith the Directory (tenant) IDteams.bot_app_idwith the Application (client) IDteams.channelswith the channel ids you want alerts posted to, one per environmentaws.alarm_emailwith the address that should receive receiver alarms
Leave teams.service_url at the Bot Framework endpoint for your region;
https://smba.trafficmanager.net/amer/ is North America.
To find a channel id: in Teams, open the channel’s ⋯ menu and choose Get link to
channel. The id is the 19:...@thread.tacv2 segment of that URL.
6. Icons
Section titled “6. Icons”Nothing to do. Both icons are committed in teams-app/, generated from the Sentinel
mark in docs/brand/assets/perch:
color.png, 192x192, opaque, square, the owl inset on the amber tileoutline.png, 32x32, transparent background, white glyph only
Teams renders the outline icon on the manifest’s accentColor, which is set to brand
navy #1b2741. teams-app/build-package.sh refuses to build without both files.
7. Build and install the Teams app
Section titled “7. Build and install the Teams app”BOT_APP_ID='<Application (client) ID>' teams-app/build-package.shTeams admin center → Teams apps → Manage apps → Upload new app → upload
teams-app/sentinel.zip.
Then install it into the team. In the Teams client open Sentinel and choose Add.
Teams presents a “Choose a place to use the app” picker listing channels; select any
channel in the team that owns your alert channels. The manifest declares team scope,
so choosing a channel installs into that channel’s parent team, not into the channel
itself. The older route reaches the same place: the team’s ⋯ → Manage team → Apps →
More apps → Sentinel.
Installing at the team scope is what lets the bot post into that team’s channels; there is no per-channel install step. If both alert channels live in the same team, one install covers both.
8. Prove it
Section titled “8. Prove it”.venv/bin/python -m scripts.bot_smoke --channel '<staging channel id>' --level errorExpected: a red-banner card in your staging alert channel, a threaded reply beneath it,
and both conversation_id= and message_id= printed. That reply is the exact mechanism
the investigation engine uses to deliver findings.
Rollback
Section titled “Rollback”Uninstalling the Teams app stops all bot posts immediately. Sentry alerts keep flowing
to the receiver, which will then fail its posts and return 500, visible in the
CloudWatch alarm and in Sentry’s delivery log. To restore stock Teams cards, run
scripts/migrate_rules.py rollback as well.