Microsoft Teams Integration

The Microsoft Teams integration sends Living Security notifications to users and channels through the Living Security Teams app. Use it for training assignments, human risk alerts, rollout messages, and security team announcements. This integration is notification-only. Users do not send commands to the bot in Microsoft Teams. When the app is installed, the bot stores the Teams conversation reference for future proactive notifications. Install messages are one-way and can be customized or disabled for enterprise rollout requirements.

A Microsoft Teams administrator must still upload, approve, and distribute the Living Security Teams app. Microsoft Entra User.Read.All admin consent is optional and enables only email or user principal name (UPN) lookup fallback.

For nudge and playbook delivery setup, start at Settings → Communications → Channels and click the Microsoft Teams card. This page covers the underlying Teams app configuration.

Prerequisites

Before configuring Microsoft Teams, ensure you have:

A Microsoft Teams administrator who can upload and approve organization apps. The same person may hold both administrator roles.
A Microsoft Entra administrator only if you want to enable optional email/UPN lookup fallback with tenant-wide User.Read.All application consent
Living Security administrator privileges
An active Living Security organization
The team and channel names where security announcements should be delivered, if channel announcements are enabled
Your Microsoft Entra tenant ID, available under Microsoft Entra admin center → Identity → Overview

Who Does What

Role	Responsibility
Living Security administrator	Connects the Microsoft tenant, downloads the regional package, configures install messages, validates setup, and sends tests
Microsoft Teams administrator	Uploads and allows the app, distributes it to the intended users or groups, and assigns app setup policies
Microsoft Entra administrator, optional	Grants `User.Read.All` application consent to the regional Bot app ID when email/UPN lookup fallback is required
Teams owner, when channel delivery is used	Installs or approves the app for the intended team and channel

These can be different people. Share the package checksum, Teams app ID, Bot app ID, and intended rollout population with the Microsoft Teams administrator. Share the generated consent URL with a Microsoft Entra administrator only when enabling the optional email/UPN lookup fallback. Do not share unrelated Living Security credentials.

Setup

Open the Microsoft Teams setup panel

In Living Security, go to Settings → Communications → Channels and select Microsoft Teams.The panel shows your organization region, package filename, Teams app ID, bot app ID, SHA256 checksum, Microsoft tenant configuration status, install instructions, install message controls, validation, and test notification tools.

The region shown in Living Security matches the region where your organization is hosted.

Connect your Microsoft tenant

In Connect your tenant, enter the Microsoft Entra tenant ID that owns the users and Teams channels receiving notifications, then click Save Microsoft tenant. One Microsoft tenant can belong to only one Living Security organization.If the tenant control is unavailable, work with your Living Security implementation owner or support contact to connect or change the tenant before installing the app.

Living Security shows Microsoft tenant connected before you continue.

Connect the tenant before installing the Teams app when possible. If the app is already installed, save the tenant and select Validate install first. Living Security attempts to associate the existing installation automatically; reinstall only if validation cannot detect it.

Download the regional Teams package

Click Download Teams package. Living Security provides a region-specific ZIP package for your organization.Verify the downloaded file against the SHA256 checksum shown in Living Security before you change anything. To give the app your own name and icons, follow Rebrand the Regional Package after this check and before you upload the package.

The checksum of the downloaded file matches the SHA256 checksum shown in Living Security.

Upload and install the package in Teams admin center

In Microsoft Teams admin center, go to Teams apps → Manage apps → Actions → Upload new app, then upload the ZIP file downloaded from Living Security.Confirm:

The Teams app ID and bot app ID match the values shown in Living Security
The app name is the regional Living Security name, or the name you set if you rebranded the package
The publisher is Living Security. Rebranding the package does not change the publisher
The app is unblocked
The app is available to the intended users or groups
The app is installed through app setup policies or targeted install for the users and teams/channels that should receive notifications

Microsoft can take time to propagate app availability and setup policy changes.

If validation or a test fails immediately after an app-policy change, confirm the policy assignment in Microsoft Teams admin center and retry after Microsoft finishes propagating it.

Install or open the app

Distribute the personal app to the intended users. Before Living Security can send a personal test to a detected installation, at least one user must install or open the Living Security personal app in Microsoft Teams. This allows the bot to capture the user’s trusted identity and personal conversation reference. A channel installation alone cannot be used for a personal detected-install test.For channel delivery, install the app in the intended team and channel so the bot can capture that channel conversation reference.

A target user has installed or opened the personal app, or the app is installed in the intended channel.

Configure install messages

In the Install message controls section, choose whether Teams install messages are sent and customize the one-way copy for your organization.Available controls:

Send install messages
Send personal install messages
Send channel install messages
Default message
Personal message
Channel message

Message fields support {{installerName}}, which resolves to the display name of the user who installed the app. Leave a personal or channel message blank to use your configured default message. If the default message is also blank, Living Security uses the built-in message for that scope.

Validate the setup

Click Validate install in Living Security. Validation checks that the regional package is available, the Microsoft tenant configuration is present and unique to this Living Security organization, regional bot credentials are configured, and an active app installation has been detected for the connected tenant.

Validation shows Validation passed before you send live notifications.

Send test notifications

For the default personal test, click Send test to detected installation. Living Security selects a detected active personal installation and uses its stored trusted identity and conversation reference. This test does not call Microsoft Graph and does not require User.Read.All consent.If no personal installation is detected, ask a user to install or open the Living Security personal app, select Validate install again, and then resend the test. Use the advanced targeted email/UPN test only when the optional lookup fallback is enabled.

The one-way test notification appears in Microsoft Teams.

Review the corresponding attempt in the Communication Log when delivery diagnostics are needed.

Rebrand the Regional Package

The regional package is a ZIP archive of three files: manifest.json, color.png, and outline.png. You can set your own app name and icons in that package before you upload it. Living Security supports this path for regional packages that a Teams administrator uploads directly. Do this after you download and verify the package, and before you upload it in Teams admin center.

Unzip the package

Extract the ZIP file. It contains exactly three files at the root of the archive: manifest.json, color.png, and outline.png.

Replace the icons

Replace color.png and outline.png with your own icons. Keep the same two file names.

File	Requirement
`color.png`	Full-color PNG, 192 × 192 pixels, no transparency
`outline.png`	Transparent PNG, 32 × 32 pixels

Set your app name

In manifest.json, edit these two fields:

name.short — the name shown in the Teams app header and other space-limited areas. Maximum 30 characters.
name.full — the name shown in the app catalog and app details. Maximum 100 characters.
If a Living Security app is already uploaded in Teams admin center, set version higher than the version installed there. Microsoft Teams refuses an update that does not increase the version, and a fresh download can carry the same version as, or a lower version than, the package you already installed.Read the installed version in Teams admin center under Teams apps → Manage apps, on the app details page. Compare it with the version value in the manifest.json you just downloaded, then set a value higher than both. Keep the three-number MAJOR.MINOR.PATCH format.For example, if the installed app is 1.1.1 and your new download is 1.1.0, set 1.1.2. Raising the downloaded 1.1.0 to 1.1.1 would repeat the installed version, and Teams would refuse the upload.

Leave the identity fields unchanged

Do not change these fields. Each one carries the app, bot, or single sign-on identity:

id
botId in bots
webApplicationInfo
validDomains
contentUrl and websiteUrl in staticTabs
A change to an identity field can leave the app installable but unable to deliver notifications or complete single sign-on. Validate install checks the tenant, the bot credentials, and the detected installation. It does not compare your manifest against the package Living Security built.

Re-zip the three files

Create a new ZIP archive from the three files. Put them at the root of the archive, with no enclosing folder. Microsoft Teams refuses a package whose manifest.json is inside a folder.

Upload and verify

Upload the rebranded ZIP file in Teams admin center, then return to Living Security and click Validate install. Send a test notification.

Validation shows Validation passed, and the test notification arrives in Microsoft Teams under your app name and icons.

Publisher and Checksum

Rebranding sets the app name and icons. It does not change two things:

The publisher stays Living Security. The manifest developer fields name Living Security and link to the Living Security website, privacy policy, and terms of service. Together they identify the company that operates the service, so Teams continues to show Living Security as the publisher on the app details page, in permission-consent dialogs, and in app usage reports. Your name and icons are what users see in the app header, the app catalog, and notifications.
The SHA256 checksum no longer matches. The checksum shown in Living Security describes the package as downloaded. Verify it before you edit the files, then record the checksum of your own rebranded package for your rollout records.

Optional: Enable Email/UPN Lookup Fallback

Normal personal delivery uses a trusted Microsoft Entra object ID already known to Living Security together with the bot conversation reference captured when the user installs or opens the app. Channel delivery uses its stored channel conversation reference. Neither route requires Microsoft Graph. If a recipient does not have a trusted Entra object ID, Living Security can optionally use Microsoft Graph to resolve the recipient by email address or UPN. To enable that fallback, ask a Microsoft Entra administrator to click Grant optional User.Read.All consent in the Teams setup panel and approve the Microsoft Graph User.Read.All application permission for the regional Living Security Teams application. The admin consent flow follows this Microsoft Entra pattern:

https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={bot-app-id}

Living Security generates this URL from the connected tenant ID and the Bot app ID shown in the setup panel. The IDs serve different purposes:

Teams app ID identifies the installable app package in Microsoft Teams admin center.
Bot app ID identifies the regional bot’s Microsoft Entra application and is the client ID used for the optional admin consent flow.

Do not substitute the Teams app ID in the consent URL. The Microsoft Entra ID (Client Credentials) integration under Connected Integrations is a separate, generic integration. Its credentials or consent cannot be reused by the regional Teams bot, and consent granted to an unrelated Entra application does not enable this fallback.

Making consent optional does not remove User.Read.All from existing regional Living Security application registrations. Customers that already granted consent can continue using email/UPN fallback without reconfiguration.

Notification Types

Depending on your organization’s entitlements and configured playbooks, Living Security can send:

Notification	Description
Training assignments	Notify users when training is assigned, due, or ready to complete
Training reminders	Remind users about upcoming deadlines
Human risk alerts	Send personalized Human Risk Index updates and recommended next steps
Rollout messages	Send one-way onboarding or rollout notifications during deployment
Channel announcements	Post security program communications to configured Teams channels

Customization

Teams notifications use your Living Security organization configuration. Supported fields include customer display name, supported logo and brand fields, message copy, calls to action, destination links, rollout text, and support/contact text. Install messages are configurable from Settings → Communications → Channels → Microsoft Teams → Install message controls. You can disable install messages entirely, disable only personal or channel install messages, and configure default, personal, or channel-specific copy. The Teams app name and icons come from the regional package. To set your own, see Rebrand the Regional Package.

Updating or Removing the App

When Living Security provides an updated regional package, download it from the Microsoft Teams channel panel and upload that package through Teams admin center. Verify the displayed app ID, bot ID, and checksum before rollout.
Branding edits do not survive a package update. Every new regional package carries the Living Security app name and icons again. Re-apply your edits with Rebrand the Regional Package before you upload the new package. Keep your icons, your two name values, and the version you last uploaded where you can find them, so each upgrade is a short repeat of the same steps. A new package does not always carry a higher version than the one you installed, so set the version from what Teams shows as installed.
Re-run Validate install and send another test after an app or policy update.
Removing or blocking the app prevents proactive notifications to that user or channel. Reinstall the app and send a new test so Living Security receives a current Teams installation event.
If you are discontinuing Teams delivery, remove Teams from the relevant playbooks before removing the app from Microsoft Teams.

Troubleshooting

A user does not receive a personal notification

Confirm the Living Security Teams personal app is installed and the user has opened it so Living Security has a current conversation reference
Confirm the configured Microsoft tenant ID is the tenant where the user is located
If diagnostics show that email/UPN fallback was attempted, confirm User.Read.All admin consent was granted to the displayed Bot app ID for the correct tenant
When email/UPN fallback is used, verify the user’s email or UPN in Living Security matches Microsoft Entra ID
Ask the user to unblock or reinstall the app if they previously removed or blocked it

A channel announcement does not appear

Confirm the Living Security Teams app is installed in the target team or channel.
Confirm the channel mapping in Living Security uses the correct team and channel.
Check whether the channel was removed, renamed, archived, or restricted.
Reinstall the app in the target team or channel and send another test notification.

The app is installed but notifications fail

Check whether the bot was blocked, removed, or uninstalled
If the app was installed before the tenant was connected in Living Security, save the tenant and select Validate install so Living Security can associate the existing installation
Reinstall only if validation cannot detect the existing installation
Confirm the target user or channel has received the latest app install event
Send a new test notification after reinstalling the app

Example install event fields used for troubleshooting:

{
  "type": "installationUpdate",
  "action": "add",
  "channelData": {
    "tenant": { "id": "278750d2-8df7-4262-a34d-08d79ad671d8" },
    "team": { "id": "19:team-id@thread.tacv2" },
    "channel": { "id": "19:channel-id@thread.tacv2" }
  },
  "conversation": {
    "id": "19:channel-id@thread.tacv2",
    "conversationType": "channel",
    "tenantId": "278750d2-8df7-4262-a34d-08d79ad671d8"
  }
}

Security

Living Security uses Microsoft Graph User.Read.All only for the optional email/UPN recipient lookup fallback. By default, personal notification routing uses a trusted Entra object ID from Living Security’s entity data and the bot conversation reference captured from Microsoft Teams. Caller-supplied object IDs and conversation references are not trusted routing data. Microsoft Teams messages are delivered through the Living Security notification-only Teams bot using Microsoft Teams proactive messaging. Living Security does not require customers to create their own Microsoft Entra app registration or share a customer-owned client secret for the standard Teams app setup. Region-specific Teams packages keep the app ID, bot ID, and messaging endpoint aligned with the Living Security region where your organization is hosted.

Email Integration

Configure email as a delivery channel.

Slack Integration

Configure Slack as a delivery channel.

Communication Log

Track Teams delivery status and history.

Authentication

Microsoft Entra ID and SSO configuration.

Integrations

Integration setup

Catalog

Outbound Channels

Prerequisites

Who Does What

Setup

Rebrand the Regional Package

Publisher and Checksum

Optional: Enable Email/UPN Lookup Fallback

Notification Types

Customization

Updating or Removing the App

Troubleshooting

Security

Email Integration

Slack Integration

Communication Log

Authentication

Integrations

Integration setup

Catalog

Outbound Channels

​Prerequisites

​Who Does What

​Setup

​Rebrand the Regional Package

​Publisher and Checksum

​Optional: Enable Email/UPN Lookup Fallback

​Notification Types

​Customization

​Updating or Removing the App

​Troubleshooting

​Security

​Related

Email Integration

Slack Integration

Communication Log

Authentication

Prerequisites

Who Does What

Setup

Rebrand the Regional Package

Publisher and Checksum

Optional: Enable Email/UPN Lookup Fallback

Notification Types

Customization

Updating or Removing the App

Troubleshooting

Security

Related