> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Teams

> Learn how to connect Opal to Microsoft Teams to send notifications and manage access requests.

You can connect Opal to Microsoft Teams to send notifications to requesters and reviewers about access requests. People can request access from Teams, and reviewers can approve or deny a request from a card.

With Opal's Microsoft Teams integration:

* **Users can** request access to resources and groups from Teams, and get notified in Teams about their requests.
* **Reviewers can** approve, deny, or admin-approve requests from a card in Teams.
* **Admins can** send access request notifications to Teams reviewer channels and audit channels.

## Requirements

To connect Microsoft Teams, you must:

* Be an [Opal Admin](https://docs.opal.dev/docs/roles-in-opal.md).
* Have a Microsoft 365 administrator consent to Opal reading directory users and operating the Teams app. Consent grants the Microsoft Graph permissions `User.Read` and `User.Read.All`, which Opal uses to match people to Entra users. Permission to create channels (`Channel.Create.Group`) is granted separately by each team owner when they install the Opal app in a team.
* Use Opal Cloud. Opal provides the Teams app. Self-hosted Opal does not set up this connection.

If Microsoft Teams does not appear under **Productivity Integrations**, it is not enabled for your organization yet.

## 1. Connect Microsoft Teams in Opal

1. In the Opal dashboard, go to **Configuration** > **Productivity Integrations**.
2. Click **Connect** on Microsoft Teams.
3. Confirm that a Microsoft 365 administrator will consent to Opal reading directory users and operating the Teams app.
4. Complete admin consent in Microsoft.

![Microsoft Teams on the Productivity Integrations page, showing it as connected](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-connect.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=4cc14fdb5480241ca5b37f29f04a801a)

When consent succeeds, Opal shows that Microsoft Teams is connected. Opal then matches people in Opal to Microsoft Entra users by email. It compares each Opal email, including secondary emails, with the Entra user's mail address and user principal name.

If admin consent is cancelled, Opal shows that Microsoft Teams admin consent was not granted. A Microsoft tenant can be connected to only one Opal organization. If it is already connected, Opal shows that the Microsoft Teams tenant is already connected. If Microsoft does not accept the consent, Opal shows that the consent could not be verified.

People with no matching Entra user do not receive Teams notifications.

## 2. Install the Opal app in Teams

Connecting the tenant does not by itself give Opal a conversation to message.

* Install the Opal app in each team where Opal should post or create channels. A team owner grants Opal permission to create standard channels in that team only. Opal does not receive tenant-wide permission to create channels.
* Each person who should receive a direct message needs the Opal app installed for themselves. Installing the app personally is enough. If an administrator pre-installs the app for someone through a Teams policy, Opal can message them only after they send the Opal bot a message.

## 3. Turn on Teams notifications

To receive Opal messages in Teams, open your avatar in the Opal dashboard, select **Settings**, and under **Notification Preferences** enable **Microsoft Teams**.

![Notification Preferences with the Microsoft Teams toggle turned on](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-notification-preferences.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=d6c4ba9626fcd15e08807e56cee89680)

The Microsoft Teams option appears only after your organization has connected Microsoft Teams. Organization notification defaults apply until a person saves their own preferences. Teams is off by default; an admin can change the organization default in the organization notification settings.

## Request access from Teams

The app name in Teams is **Opal**.

In a channel or group chat, use the slash command:

* `/Opal request` posts a card with a **Request access** button.
* `/Opal search aws` searches for requestable resources and groups. Replace `aws` with the term you want. Opal shows up to 8 matches, and each match has a **Request** button.

In a 1:1 chat with the Opal bot, `request` and `search aws` work with or without a leading slash.

These do not start a request:

* A message that is only `opal`
* An @mention of the bot
* An ordinary channel or group-chat message that is not a slash command

You can also choose **Request access** from the compose box.

Requesting has two steps:

1. Search for an asset to request. Select a resource or group, then **Continue**. If the item is not listed, the card links to the catalog in Opal.
2. Fill in the request. When the item has named access levels, choose one. Choose a duration: 1 hour (the default), 8 hours, 1 day, 7 days, or Indefinite. Enter a reason, which is always required in Teams, then choose **Submit request**. Opal confirms that the request was submitted and links to it.

![Step 1 of the Teams request dialog, searching for an asset to request](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-request-search.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=80a852a3655f49622e19b702f10721d6)

![Step 2 of the Teams request dialog, with duration and reason fields](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-request-details.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=3de974fcf1f64c94a1678f7cb5e8294f)

The duration list is the same for every item and does not reflect the item's maximum duration. If Opal cannot submit the request from Teams, request it in Opal instead.

A search with no term asks you to provide a query after the search command. If Teams cannot match the person to an Opal user, Opal says it couldn't find an Opal user for this Teams account.

## Act on requests from cards

Opal sends cards in Teams for access requests.

Reviewers can **Approve** or **Deny** from the card. **Admin Approve** is included when that reviewer can admin-approve the request. Type a reason in the card before **Deny** or **Admin Approve**. A reason on **Approve** is optional.

![A reviewer card in Teams with a reason field and Approve, Deny, and Admin Approve buttons](https://mintcdn.com/opalsecurity/LoClk8Jrd62X2oU_/images/docs/microsoft-teams-reviewer-card.png?fit=max\&auto=format\&n=LoClk8Jrd62X2oU_\&q=85\&s=b76434eaff13310ec4425fccba63d8a3)

Opal confirms the action in Teams. Approval and admin approval report that propagation is in progress. A denial reports that the request was denied. When the request is resolved, the card updates in place.

An expiration alert includes **Extend access** when an extension is allowed. Otherwise, its **Request** button opens the request in Opal. If external request approvals are turned off, the alert still shows the button, and choosing it says that external request approvals are disabled in Opal.

Comments on a request are sent to each reviewer's chat with the Opal bot. Teams 1:1 chats have no reply threads, so each comment arrives as a new message.

If the request was already approved or denied, Opal says that it has already been actioned. If the person who clicks does not have permission to review the request, Opal says so. If the request requires MFA to approve, Opal asks the reviewer to complete MFA in Opal.

Requesters receive a card for their own request, with **Cancel** and, when the request requires manager approval, **Escalate to skip-manager**.

![A requester card in Teams with a Cancel button](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-requester-card.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=2952822150740d58db68822d63e01af7)

If external request approvals are turned off for your organization, new request cards do not show review or requester buttons, and people act on the request in Opal. A button on a card sent before the setting was turned off tells the person that external request approvals are disabled in Opal.

## Reviewer channels

A Teams channel can be the reviewer message channel for an owner. Opal notifies that channel when there is an access request to review for the owner. The channel is available to select after the Opal app is installed in that team.

## Audit channels

Opal can notify a Teams channel about events for a resource or group.

On the resource or group, open **Audit channels** and choose **Create a Teams channel**. Select a team where the Opal app is installed, enter a channel name, and create it.

![The Create a Teams channel dialog with a team and channel name](https://mintcdn.com/opalsecurity/qRshVqcvyMC1wZin/images/docs/microsoft-teams-create-channel.png?fit=max\&auto=format\&n=qRshVqcvyMC1wZin\&q=85\&s=d9dd98717afeb104c49b6ac6625565a1)

Opal creates a standard channel. If that name is already taken, Opal shows that a channel with this name already exists in Microsoft Teams. If the installed app is out of date, Opal asks you to update the Opal Teams app to grant channel creation access.

Audit channels receive access request cards and notices when access is added or removed.

Existing standard channels in a team are added automatically when the Opal app is installed in that team, and you can select them from the list. Opal does not link an existing Teams channel by pasting a channel ID, and it does not create private Teams channels.

## Limitations

* This connection is for Opal Cloud. Self-hosted Opal does not configure the Teams app.
* A Microsoft tenant can be connected to only one Opal organization.
* Direct messages require the Opal app installed for that person. If an administrator pre-installed it, the person must message the bot once first.
* Disconnecting Microsoft Teams in Opal stops Opal from sending to or receiving from Teams for your organization.
* Opal creates standard channels only in teams where the app is installed.
* The Teams request form is a two-step dialog. The duration choices are always 1 hour, 8 hours, 1 day, 7 days, and Indefinite, and a reason is always required.
* Some notifications are not sent to Teams, including access expired, access extended, and access review revocations. See [Notifications](https://docs.opal.dev/docs/notifications.md) for which notifications reach Teams.
* People enable Microsoft Teams in their own notification preferences. Someone with no matching Entra user, or with no conversation with the bot, does not receive a direct message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.