Set up the Teams connector

Configure the Microsoft Teams connector to index channel and chat messages. For a new calendar or meeting transcript connection, use the separate Outlook Calendar connector. See Set up Outlook Calendar.

Before you start

Have these in place before you configure the connector, so your IT or security team can approve everything in one request:

• Global Administrator: The person performing setup must be a Microsoft 365 Global Administrator (to register the app and grant admin consent) and a Glean admin who can add and configure connectors.
• A Microsoft 365 tenant with Teams enabled — plus the ability to register an application in Microsoft Entra ID (Azure Active Directory) with access to Microsoft Graph API v1.0.
• Authentication credentials — a client certificate and PKCS#8 private key (recommended) or a client secret, plus your application (client) ID and directory (tenant) ID. Glean recommends certificate-based authentication because Microsoft is phasing out client-secret authentication for these APIs, though client secrets still work.
• An admin must approve the required Microsoft Graph permissions. Crawling uses application permissions. Private and meeting chat crawling requires Chat.Read.All. Data fetching requires additional delegated permissions. Share the required permissions with your security team before you start.

Required permissions

Grant the messaging app the Microsoft Graph application permissions in this table. Add Chat.Read.All if you enable private or meeting chat crawling.

For data fetching, also add the delegated permissions to the same messaging app and grant tenant-wide admin consent. See Enable data fetching for Teams messages.

Application permission	Purpose	When required
User.Read.All	Read user profiles for identity mapping	Always
GroupMember.Read.All	Read group membership to discover teams and map access	Always
Team.ReadBasic.All	List teams and read team metadata	Always
ChannelSettings.Read.All	List channels and read channel metadata	Always
ChannelMember.Read.All	Read channel membership to enforce access	Always
ChannelMessage.Read.All	Read channel messages and replies and subscribe to changes	Always
Chat.Read.All	Read private and meeting chats and their membership	When private or meeting chat crawling is enabled

For an existing Teams-based calendar connection, grant transcript permissions to its separate transcript app. Don't add them to the messaging app as a substitute. See Teams transcripts.

Known limitations

• This connector doesn't cover SharePoint-backed team sites. SharePoint handles the associated file uploads.
• For indexed search, Glean crawls only Teams content that belongs to the Microsoft 365 tenant where you configure the connector. Cross-tenant and external Teams content aren't supported by the crawler.

Setup steps

Microsoft Teams setup (Azure)

Before configuring the connector in Glean, register and configure an application in Microsoft Entra ID.

1. Register an application

1. Sign in to the Azure portal. Select Microsoft Entra ID, then Manage → App registrations → New registration.

2. On the Register an application page, register an app with the following:

   Field	Value
   Name	Glean MSFT Teams App (for messages)
   Supported account types	Accounts in this organizational directory only (Single tenant)
   Redirect URI	Leave blank for crawling only. For data fetching, add a redirect URI for the Web platform. See Enable data fetching for Teams messages.

3. Click Register.

   

2. Add and grant API permissions

1. In the app registration, go to Manage → API permissions.

2. Click Add a permission and select Microsoft Graph. Choose Application permissions and add the crawler permissions from the required permissions. Add the delegated permissions separately if you plan to use data fetching.

   

3. After you add all permissions, click Grant admin consent for tenant.

3. Generate a certificate and private key

Generate a certificate and a PKCS#8 private key using OpenSSL. OpenSSL is installed by default on macOS and Linux. On Windows, install a third-party OpenSSL build and add its \bin directory to your PowerShell PATH.

1. Run the following commands. Microsoft requires the certificate to be verified with a private key in PKCS#8 syntax.

   openssl genrsa -out tempprivatekey.key 2048
   openssl pkcs8 -topk8 -inform PEM -outform PEM -in tempprivatekey.key -out privatekey.key -nocrypt
   openssl req -new -key privatekey.key -out request.csr
   openssl x509 -req -days 365 -in request.csr -signkey privatekey.key -out certificate.crt

2. Verify that both certificate.crt and privatekey.key conform to these formats:

   • certificate.crt starts with a BEGIN CERTIFICATE header and ends with an END CERTIFICATE footer.
   • privatekey.key starts with a BEGIN PRIVATE KEY header and ends with an END PRIVATE KEY footer. It must not include RSA in the header and must not be encrypted.
   warning

   The private key must be in PKCS#8 format. A PKCS#1 key (a BEGIN RSA PRIVATE KEY header) uploads successfully but fails when you save the connector. Convert it with: openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey.key -out privatekey_pkcs8.key -nocrypt.

4. Upload the certificate to Azure

1. Navigate back to Microsoft Entra ID → Manage → App registrations and select the app you created. Then click Manage → Certificates & secrets.

2. Select the Certificates tab and click Upload certificate.

3. Upload the certificate.crt file you generated.

   

4. Click Overview and copy the Application (client) ID and Directory (tenant) ID. You'll enter these in Glean.

   note

   If an existing Teams-based calendar connection shares this certificate between its messaging and transcript apps, upload it to both registrations. This requirement doesn't apply to unrelated apps or the standalone Outlook Calendar connector.

Client secret setup (alternative)

Instead of a certificate, you can authenticate with a client secret:

1. After granting admin consent, go to Manage → Certificates & secrets and click New client secret. Enter a description, select 24 months for expiry, then click Add.

2. Copy the Value (not the Secret ID). It appears only once.

   

Configure Glean

1. Start connector setup

1. In the Glean Admin console, go to Connectors → Add connector.
2. Search for Microsoft Teams and select the connector.
3. Provide a Name and optional Icon for the connector.

2. Provide credentials

• Directory (tenant) ID
• Application (client) ID
• For certificate-based authentication: upload the Client certificate (certificate.crt) and the Private key (privatekey.key, PKCS#8).
• For client secret authentication: enter the Client secret value you generated.

3. Configure optional crawl settings

• Allow crawling Teams private chats: Enables crawling of 1:1 (direct) chats and group chats. Glean treats group chats as private chats, so turning off this setting excludes both.
• Allow crawling Teams meeting chats: Enables crawling of meeting chat messages.

To index only channel messages, turn off both settings. Glean then crawls teams and their channel messages, and excludes 1:1, group, and meeting chats.

4. Save and start the initial crawl

Click Save to complete setup. Glean starts an initial crawl of Teams content.

Enable data fetching for Teams messages

Data fetching lets Glean search for and retrieve messages directly from Microsoft Teams using each user's access. You can enable it during connector setup or for an existing connector.

Prerequisites

Use the same Microsoft Entra app registration that your organization uses for Teams crawling. The Application (client) ID in Glean identifies this app. Don't use a separate transcript or bot app. Keep the crawler app's existing application permissions and credentials. You can authenticate with either a certificate or a client secret.

Limitations

Data fetching respects the signed-in user's Teams access. These limits apply:

• Data fetching supports Teams messages, not meeting events or transcripts.
• Searching directly from Teams returns private, group, and meeting chat messages only when both Allow crawling Teams private chats and Allow crawling Teams meeting chats are on. If either setting is off, this search excludes all chat messages. Retrieving a specific chat message respects the setting for that chat type.
• Retrieving a chat message returns that message, not the surrounding conversation.
• Retrieving a channel reply returned by search can fail because Microsoft doesn't include the thread's root message ID in the search response.

Configure the existing Teams app

Add delegated permissions and a redirect URI to the Teams crawler app:

1. In Microsoft Entra ID → Manage → App registrations, open the Teams crawler app.
2. Go to Manage → API permissions → Add a permission → Microsoft Graph → Delegated permissions and add these four permissions:

   Delegated permission	Purpose
   User.Read	Sign in and read the user's profile.
   offline_access	Refresh delegated access without requiring the user to sign in again.
   Chat.Read	Search messages and retrieve chat messages as the signed-in user.
   ChannelMessage.Read.All	Read channel messages and thread replies as the signed-in user.

3. Click Grant admin consent for tenant. Consent from individual users doesn't satisfy the connector's tenant-wide consent validation.
4. Under Manage → Authentication, add a redirect URI for the Web platform using this format:

   https://<your-Glean-backend-host>/instance/microsoftteams/oauth/verify_code

   Use the Glean OAuth host for your deployment, not your Microsoft tenant URL. Contact Glean Support if you don't know which host to use. The path always uses lowercase microsoftteams, including for named connector instances. Don't use o365 or a connector instance name such as microsoftteams_0.
5. Save the redirect URI.

Turn on data fetching in Glean

Complete the Entra app changes before enabling Data fetching:

• For a new connector, select Data fetching during setup and click Save after completing the required fields.
• For an existing connector, go to Admin console → Connectors, open the Teams connector, and turn on Data fetching in the Overview tab.

Glean validates the delegated permissions, tenant-wide consent, and callback URL. If validation fails, see TEAMS_LIVEMODE for troubleshooting.

Each user must then authorize their Microsoft Teams account in Settings → Connectors or through the authorization prompt after searching for Teams content. This authorization is separate from SharePoint and OneDrive authorization. Admin consent doesn't replace this user step.

Existing calendar connections

If your Teams connector still manages calendar events and transcripts, keep its configuration. The transcript-specific app, permission, and application access policy instructions remain available for that setup. See Teams transcripts.

Contact your Glean account team before changing this connection. Don't delete its calendar configuration or replace its credentials to switch to Outlook Calendar.

Supported API endpoints

Endpoint	Permissions	Purpose
GET /users	User.Read.All	Reads all user profiles for identity crawl.
GET /groups	GroupMember.Read.All	Lists groups, discovering Microsoft 365 groups provisioned as teams.
GET /groups/{groupId}/members	GroupMember.Read.All	Reads direct backing-group memberships for team access.
GET /users/{userId}/teamwork/associatedTeams	Team.ReadBasic.All	Lists teams associated with a user.
GET /teams/{teamId}/channels	ChannelSettings.Read.All	Lists channel metadata.
GET /teams/{teamId}/channels/{channelId}/members	ChannelMember.Read.All	Reads channel membership.
GET /teams/{teamId}/channels/{channelId}/messages	ChannelMessage.Read.All	Reads channel root messages.
GET /teams/{teamId}/channels/{channelId}/messages/delta	ChannelMessage.Read.All	Reads channel message delta pages.
POST /subscriptions	ChannelMessage.Read.All	Creates change-notification subscriptions.
GET /users/{userId}/chats	Chat.Read.All	Lists chats when private or meeting chat crawl is enabled.
GET /chats/{chatId}/messages	Chat.Read.All	Reads private or meeting chat messages.

Crawling and freshness

• Full crawls re-enumerate teams, channels, chats, and supported content.
• Incremental crawls fetch newly created and recently updated content since the last crawl.
• Real-time updates — Glean subscribes to Microsoft Graph change notifications (webhooks) for near real-time channel content updates, subject to Microsoft subscription limits.

Troubleshooting

The private key must be in PKCS#8 format (a BEGIN PRIVATE KEY header). Convert a PKCS#1 key with:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey.key -out privatekey_pkcs8.key -nocrypt

Upload the certificate to the Entra ID app registration that uses it. If an existing Teams-based calendar connection shares the certificate between its messaging and transcript apps, upload it to both registrations.

The uploaded private key does not correspond to the uploaded certificate. Make sure privatekey.key and certificate.crt are the matching pair generated together in step 3.

For an existing Teams-based calendar connection, check that its application access policy authorizes the transcript app for the relevant users. See Teams transcripts and TEAMS-2. For a standalone connection, see Outlook Calendar troubleshooting.

Confirm the user is a member of the relevant teams, channels, or chats, and that the required Graph permissions were granted and admin-consented.