# Microsoft Teams authentication

> This document describes how to authenticate Microsoft Teams with **UiPath Integration Service** using OAuth 2.0. The Microsoft Teams connector supports **user-based OAuth authentication**, with optional support for **custom OAuth applications** and **bot-enabled scenarios**.

This document describes how to authenticate Microsoft Teams with **UiPath Integration Service** using OAuth 2.0. The Microsoft Teams connector supports **user-based OAuth authentication**, with optional support for **custom OAuth applications** and **bot-enabled scenarios**.

## Overview

The following table summarizes the supported authentication options and their prerequisites.

| Authentication Scenario | Description | Prerequisites |
| --- |  --- |  --- |
| **Bring Your Own OAuth App (BYOA)** | Uses a customer-managed Azure AD application | Azure AD app, Client ID, Client Secret, Tenant ID, admin consent |

## Bring Your Own OAuth App (BYOA) configuration

Configure your Azure AD application as follows.

### Azure application settings

| Setting | Value |
| --- |  --- |
| OAuth flow | Authorization Code |
| Redirect / Callback URL | `https://{yourDomain}/provisioning_/callback` |
| Supported account types | Single-tenant or Multi-tenant |
| API | Microsoft Graph |

### Tenant ID

| App Type | Tenant ID |
| --- |  --- |
| Multi-tenant | `common` |
| Single-tenant | Azure tenant ID |

:::note
UiPath supports both single-tenant and multi-tenant applications.
:::

## Scopes and permissions

Scopes control what actions UiPath can perform in Microsoft Teams. Scopes are configurable during connection creation.

### Mandatory scopes

The following scopes are **mandatory** and **must not be removed**. They are required for a successful connection.

| Scope | Purpose |
| --- |  --- |
| `openid` | User authentication and ID token generation |
| `offline_access` | Enables refresh token issuance |
| `User.Read` | Reads signed-in user profile |

:::note
Removing any mandatory scope will result in connection or runtime authentication failures.
:::

### All scopes

The following scopes enable common Microsoft Teams automation scenarios.

| Scope | Use case | Activity or event |
| --- | --- | --- |
| `openid` | By using this permission, an app can receive a unique identifier for the user in the form of the sub claim. The permission also gives the app access to the `UserInfo` endpoint. The `openid` scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens. The app can use these tokens for authentication | N/A |
| `offline_access` | Required to receive refresh token in the authentication request endpoint. When you redeem an authorization code in the OAuth 2.0 authorization code flow without offline\_access scope, you will not receive refresh token from the /token endpoint. | N/A |
| `profile` | Retrieving the current user profile such as name, username, email etc., so that it could be used as default/authenticated user at the connection creation and in certain activities | N/A |
| `email` | Allows the app to read all your users' primary email addresses, for sending messages or inviting them to a channel | Send Individual Chat Message, Invite Member to Channel, Invite User to Team |
| `User.Read` | Allows users to sign-in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users | Get Record → Me |
| `Team.Create` | Create a team for inviting and engaging the respective users | Insert Record → Teams |
| `Team.ReadBasic.All` | Retrieve the list of teams to be selected in the activities, such as sending a channel message etc. | Create Channel, List All Channels, Send Chat Message, Send Individual Chat Message, Invite Member to a Channel, Reply to a Channel Message, Send Channel Message, Get Team by Name |
| `TeamMember.ReadWrite.All` | Add member to a team on behalf of the signed-in user  Retrieve the list of members of a team | List All Team Members, Invite User to Team, Get Team by Name, Insert Record → Teams members, List All Records → Teams members |
| `Channel.Create` | Create a channel (standard/private) for inviting and engaging the respective users of the team | Create Channel |
| `Channel.ReadBasic.All` | Retrieve the list of channels of a team to be selected in the activities such as sending a channel message etc. | Get Channel by Name, Invite Member to a Channel, List All Channels, List Channel by Name, Reply to Channel Message, Send Channel Message |
| `ChannelMember.ReadWrite.All` | Add member to a channel on behalf of the signed-in user  Retrieve the list of members involved in a channel | Invite Member to a Channel, List All Records → Teams channels members |
| `ChannelMessage.Send` | Send a message in a channel. Also, reply to a message in a thread, if needed. | Reply to Channel Message, Send Channel Message |
| `ChannelMessage.Read.All` | Allows the app to read all channel messages in Microsoft Teams, without a signed-in user  Also used to trigger events whenever a message is posted in the channel or whenever a keyword is mentioned in the channel | Reply to Channel Message, List all Channel Messages, List All Records → Teams channels messages, When a message posted in channel (Future), When a keyword or username is mentioned in channel (Future) |
| `Chat.ReadWrite` | Allows the app to read and send your 1:1  Allows the app to read and send group chat messages  Also used to trigger events whenever a chat message is posted | Send Group Chat Message, Send Individual Chat Message, List All Chat Messages, List All Records → Chats, When a chat message is posted (Future) |
| `ChatMember.ReadWrite` | Add member to a chats on behalf of the signed-in user  Retrieve the list of members involved in a chat | Insert Record → Chats members, List All Records → Chats members |
| `Calendars.ReadWrite` | Create an Outlook calendar entry of the online Teams meeting. | Create Online Teams Meeting |
| `OnlineMeetings.ReadWrite` | Create an online meeting in Microsoft Teams and retrieve the meeting ID, passcode and URL on behalf of the current user. | Create Online Teams Meeting |
| `Files.Read.All` | Retrieve the file information that was uploaded to SharePoint in order to share it in a Teams channel or chat | Send Channel Message Send Group Chat Message, Send Individual Chat Message, Reply to Channel Message |

Scopes can be added or removed to follow **least-privilege** principles.

## Refresh tokens for OAuth applications

Refresh tokens for OAuth applications can be invalidated or revoked at any time by Microsoft. This can happen for different reasons, such as timeouts and revocations.
For details, see Microsoft's official [documentation](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens#token-expiration).

:::note
Token invalidation results in failed connections and automations are unable to run without fixing connections.
:::

This issue affects all Microsoft Graph-based connectors.

Make sure to follow best practices from Microsoft when creating your OAuth applications. For full details on how to create a Microsoft OAuth app, check the Microsoft [documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2).

## Grant permissions

To use your own private OAuth 2.0 app, you must grant consent to the application's permissions. Follow the steps described in [Grant org-wide admin consent to an app's permissions](https://learn.microsoft.com/en-us/microsoftteams/manage-consent-app-permissions#grant-org-wide-admin-consent-to-an-apps-permissions).

## Add the Microsoft Teams connection

To create a connection to your Microsoft Teams instance, you need to perform the following steps:

1. Select Integration Service from the left rail.
2. From the **Connectors** list, select **Microsoft Teams**. You can also use the search bar to narrow down the connector.
3. Select **Connect to Microsoft Teams**.
4. You are now redirected to the connection page.
5. Enter the required credentials.
6. Select **Connect**.

For more information about authenticating in Microsoft Teams, refer to the Microsoft [Authentication and authorization](https://docs.microsoft.com/en-us/graph/auth-v2-service?view=graph-rest-1.0#4-get-an-access-token) page.