Skip to content

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.

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.

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.

Terminal window
BOT_CLIENT_SECRET='<the value>' \
SENTRY_WEBHOOK_SECRET='<from the Sentry setup>' \
SENTRY_API_TOKEN='<from the Sentry setup>' \
scripts/put-parameters.sh

This 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.

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.

In config/receiver.yaml, replace:

  • teams.tenant_id with the Directory (tenant) ID
  • teams.bot_app_id with the Application (client) ID
  • teams.channels with the channel ids you want alerts posted to, one per environment
  • aws.alarm_email with 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.

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 tile
  • outline.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.

Terminal window
BOT_APP_ID='<Application (client) ID>' teams-app/build-package.sh

Teams 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.

Terminal window
.venv/bin/python -m scripts.bot_smoke --channel '<staging channel id>' --level error

Expected: 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.

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.