---
title: Elastic Microsoft Teams connector reference
description: The Microsoft Teams connector is written in Python using the Elastic connector framework. View the source code for this connector (branch main, compatible...
url: https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-teams
products:
- Elasticsearch
applies_to:
- Elastic Cloud Serverless: Preview
- Elastic Stack: Planned
---
# Elastic Microsoft Teams connector reference
The Microsoft Teams connector is written in Python using the [Elastic connector framework](https://github.com/elastic/connectors/tree/main).
View the [source code for this connector](https://github.com/elastic/connectors/tree/main/app/connectors_service/connectors/sources/microsoft_teams) (branch *main*, compatible with Elastic *9.6*).
## **Self-managed connector reference**
### Availability and prerequisites
This connector is available as a self-managed connector.
This self-managed connector is compatible with Elastic versions **9.6.0+**.
To use this connector, satisfy all [self-managed connector prerequisites](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/self-managed-connectors).
This connector is in **technical preview** and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Technical preview features are not subject to the support SLA of official GA features.
### Create a Microsoft Teams connector
#### Use the UI
To create a new Microsoft Teams connector:
1. In the Kibana UI, search for "connectors" using the [global search field](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3941/explore-analyze/query-filter/filtering#_finding_your_apps_and_objects) and choose the "Elasticsearch" connectors.
2. Follow the instructions to create a new **Microsoft Teams** self-managed connector.
#### Use the API
You can use the Elasticsearch [Create connector API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-connector) to create a new self-managed Microsoft Teams self-managed connector.
For example:
```json
{
"index_name": "my-elasticsearch-index",
"name": "Content synced from Microsoft Teams",
"service_type": "microsoft_teams"
}
```
The user needs the cluster privileges `manage_api_key`, `manage_connector` and `write_connector_secrets` to generate API keys programmatically.
To create an API key for the connector:
1. Run the following command, replacing values where indicated. Note the `encoded` return values from the response:
```json
{
"name": "connector_name-connector-api-key",
"role_descriptors": {
"connector_name-connector-role": {
"cluster": [
"monitor",
"manage_connector"
],
"indices": [
{
"names": [
"index_name",
".search-acl-filter-index_name",
".elastic-connectors*"
],
"privileges": [
"all"
],
"allow_restricted_indices": false
}
]
}
}
}
```
2. Update your `config.yml` file with the API key `encoded` value.
Refer to the [Elasticsearch API documentation](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-connector) for details of all available Connector APIs.
### Usage
To use this connector as a **self-managed connector**, use the **Microsoft Teams** tile from the connectors list **Customized connector** workflow.
For additional operations, see [*Connectors UI in Kibana*](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/connectors-ui-in-kibana).
### Connecting to Microsoft Teams
The connector connects to Microsoft Teams using application credentials (client secret or certificate), the same approach as SharePoint Online and Outlook. You do not need to install a Teams app in every team or chat.
When [document level security (DLS)](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/document-level-security) is enabled, search results are restricted to users who belong to the relevant team, channel, or chat. The connector application itself can read content according to the permissions you grant below.
To connect to Microsoft Teams, [register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) and grant it the required Microsoft Graph application permissions. Follow these steps:
1. In the [Microsoft Entra admin center](https://entra.microsoft.com), register a new application (confidential client).
2. Record the **Directory (tenant) ID** and **Application (client) ID**.
3. Create either:
- a **client secret** (Certificates & secrets → New client secret), or
- a **certificate** (upload a certificate and keep the matching private key).
4. Under **API permissions**, add and grant **admin consent** for the following Microsoft Graph **application** permissions:
- `Team.ReadBasic.All` — read teams in your organization
- `TeamMember.Read.All` — read who belongs to each team
- `User.ReadBasic.All` — read user profiles
- `Channel.ReadBasic.All` — read channels
- `ChannelMember.Read.All` — read who can access each channel
- `ChannelMessage.Read.All` — read channel messages and replies
- `Chat.Read.All` — read chats, messages, and replies
- `Files.Read.All` — read file attachments (required when **Fetch attachment content** is enabled)
5. Click **Grant admin consent** to approve the permissions. This step requires administrative privileges. If you are not an admin, request that an admin grant consent via the Entra admin center.
The connector requires **application** permissions. It does not support delegated permissions (scopes) or username/password authentication.
#### Protected APIs
`ChannelMessage.Read.All` and `Chat.Read.All` are [protected Teams APIs](https://learn.microsoft.com/en-us/graph/teams-protected-apis). Admin consent alone may not be enough — some tenants also need Microsoft to approve access for your application before message content can be read.
### Configuration
The following configuration fields are available:
Unique identifier for your Microsoft Entra tenant. Example:
- `123a1b23-12a3-45b6-7c8d-fc931cfb448d`
Unique identifier for your Entra application. Example:
- `ab123453-12a2-100a-1123-93fd09d67394`
Authentication method to use with Microsoft Graph. Options:
- `secret` (default) — authenticate with a client secret.
- `certificate` — authenticate with a certificate and private key.
(required if `auth_method` is `secret`) Client secret value from the **Certificates & secrets** tab of your Entra application. Example:
- `eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu`
(required if `auth_method` is `certificate`) Content of the certificate file uploaded to your Entra application.
(required if `auth_method` is `certificate`) Content of the private key file that matches the uploaded certificate.
Toggle to index files from channel folders and message attachments, and extract their content. Requires the `Files.Read.All` application permission. Default value is `true`.
Toggle to enable the [self-managed local extraction service](/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-content-extraction#es-connectors-content-extraction-local) for file content. Requires that ingest pipeline settings disable text extraction. Default value is `false`.
Toggle to enable [document level security (DLS)](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/document-level-security). When enabled:
- Full syncs fetch access control lists for each document and store them in the `_allow_access_control` field.
- Access control syncs fetch users' access control lists and store them in a separate index.
Default value is `false`.
#### Deployment using Docker
You can deploy the Microsoft Teams connector as a self-managed connector using Docker. Follow these instructions.
Download the sample configuration file. You can either download it manually or run the following command:
```sh
curl https://raw.githubusercontent.com/elastic/connectors/main/app/connectors_service/config.yml.example --output ~/connectors-config/config.yml
```
Remember to update the `--output` argument value if your directory name is different, or you want to use a different config file name.
Update the configuration file with the following settings to match your environment:
- `elasticsearch.host`
- `elasticsearch.api_key`
- `connectors`
If you’re running the connector service against a Dockerized version of Elasticsearch and Kibana, your config file will look like this:
```yaml
# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key:
connectors:
-
connector_id:
service_type: microsoft_teams
api_key:
```
Using the `elasticsearch.api_key` is the recommended authentication method. However, you can also use `elasticsearch.username` and `elasticsearch.password` to authenticate with your Elasticsearch instance.Note: You can change other default configurations by simply uncommenting specific settings in the configuration file and modifying their values.
Run the Docker image with the Connector Service using the following command:
```sh
docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.5.2 \
/app/bin/elastic-ingest \
-c /config/config.yml
```
Refer to [`DOCKER.md`](https://github.com/elastic/connectors/tree/main/docs/DOCKER.md) in the `elastic/connectors` repo for more details.
Find all available Docker images in the [official registry](https://www.docker.elastic.co/r/integrations/elastic-connectors).
We also have a quickstart self-managed option using Docker Compose, so you can spin up all required services at once: Elasticsearch, Kibana, and the connectors service. Refer to this [README](https://github.com/elastic/connectors/tree/main/scripts/stack#readme) in the `elastic/connectors` repo for more information.
#### Content Extraction
Refer to [Content extraction](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-content-extraction).
### Documents and syncs
The connector syncs the following content from Microsoft Teams:
- **Teams**
- **Channels**
- **Channel messages** (including thread replies)
- **Chats** (one-on-one, group, and meeting chats), including messages and thread replies
- **Users** from your Microsoft Entra directory
- **Files** (when **Fetch attachment content** is enabled): files from channel folders and message attachments
Private and shared channels are included. Each file is indexed once, even when it appears in a channel folder and as a message attachment.
- Content from files bigger than 10 MB won’t be extracted by default. Use the [self-managed local extraction service](/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-content-extraction#es-connectors-content-extraction-local) to handle larger binary files.
- Permissions are not synced by default. Enable [document-level security (DLS)](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/document-level-security) to sync permissions. Otherwise, **all documents** indexed to an Elastic deployment will be visible to **all users with access** to that Elastic Deployment.
- If the connector is missing required permissions, the sync fails rather than indexing an incomplete set of content.
#### Upgrading from earlier connector versions
Applies when upgrading to **9.6.0+** from a Microsoft Teams connector that used username/password or delegated Graph authentication.If you already have a legacy Microsoft Teams connector or index, **prefer deleting the old connector and index** and creating a new connector with a fresh index. That avoids leftover documents from the previous connector (calendars, tabs, meeting recordings, and other content types that are no longer synced).If you upgrade in place, the first successful full sync removes documents the new connector no longer produces, including:
- calendars
- channel and chat tabs
- meeting recordings
- legacy team member records (replaced by user profiles)
After upgrading, reconfigure the connector for application-only authentication (client secret or certificate). Username and password fields are no longer supported.Calendars, meeting recordings, and tabs are no longer synced by this connector. Use the [Outlook connector](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-outlook) for calendars and the [SharePoint Online connector](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-sharepoint-online) for SharePoint-hosted meeting recordings.
#### Sync types
[Full syncs](/elastic/docs-builder/docs/3941/reference/search-connectors/content-syncs#es-connectors-sync-types-full) are supported by default for all connectors.
This connector does not support [incremental syncs](/elastic/docs-builder/docs/3941/reference/search-connectors/content-syncs#es-connectors-sync-types-incremental).
### Document level security
Document level security (DLS) enables you to restrict access to documents based on a user's permissions. Refer to [configuration](#es-connectors-microsoft-teams-configuration) on this page for how to enable DLS for this connector.
When DLS is enabled, users only see Teams, channels, chats, messages, and files they have access to in Microsoft Teams. User profile documents from your directory are not restricted by DLS.
Refer to [DLS in Search Applications](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-dls-e2e-guide) to learn how to ingest data from a connector with DLS enabled, when building a search application. The example uses SharePoint Online as the data source, but the same steps apply to every connector.
### Sync rules
[Basic sync rules](/elastic/docs-builder/docs/3941/reference/search-connectors/es-sync-rules#es-sync-rules-basic) are identical for all connectors and are available by default.
### Advanced Sync Rules
Advanced sync rules are not available for this connector in the present version.
### End-to-end Testing
The connector framework enables operators to run functional tests against a real data source. Refer to [Connector testing](/elastic/docs-builder/docs/3941/reference/search-connectors/self-managed-connectors#es-build-connector-testing) for more details.
To perform E2E testing for the Teams connector, run the following command:
```shell
$ make ftest NAME=microsoft_teams
```
For faster tests, add the `DATA_SIZE=small` flag:
```shell
make ftest NAME=microsoft_teams DATA_SIZE=small
```
### Known issues
- Messages in one-on-one chats for *Chat with Self* users are not fetched via Graph APIs. Therefore, these messages won’t be indexed into Elasticsearch.
Refer to [Known issues](https://www.elastic.co/elastic/docs-builder/docs/3941/release-notes/elasticsearch/known-issues) for a list of known issues for all connectors.
### Troubleshooting
See [Troubleshooting](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-troubleshooting).
### Security
See [Security](https://www.elastic.co/elastic/docs-builder/docs/3941/reference/search-connectors/es-connectors-security).