Microsoft Connectors
Integrate with Entra ID for user mappings. Index SharePoint sites and Teams channels.
The Microsoft connectors support:
- Entra ID - for resolving user mappings across apps as an Identity Provider
- SharePoint - for indexing sites, docs, spreadsheets, slides, and other files
- Teams - for indexing channels, chat, and messages
- OneDrive - for indexing docs, spreadsheets, slides, and other files
- Outlook - for indexing emails and calendar events
Security Best Practice: Separate App Registrations
We recommend creating separate App Registrations for each Microsoft source you plan to use. This follows the principle of least privilege and provides:
- Reduced attack surface - Each connector only has the minimum permissions required
- Better audit trails - Azure logs can isolate which application accessed which data
- Independent lifecycle management - Rotate certificates, disable connectors, or modify permissions without affecting other sources
- Granular admin consent - Security teams can approve smaller, focused permission requests
- Independent rate limits - Each App Registration has separate Microsoft Graph API rate limits, preventing sources from competing for shared quotas in large environments
Architecture Options
Choose the approach that best fits your organization’s security and scale requirements:
Option 1: Separate App Registration per Source (Recommended)
Create individual App Registrations for:
- Entra ID (if using as identity provider)
- SharePoint
- Teams
- OneDrive
- Outlook
Each registration gets only the permissions needed for that specific source.
Option 2: Single Shared App Registration (Evaluation Only)
Use one App Registration for all sources. This requires the superset of all permissions and is not recommended for production environments due to security and rate limiting concerns.
Prerequisites
Before configuring any Microsoft connector, ensure you have:
Azure Access Requirements
- Azure tenant with appropriate licensing (Microsoft 365 E1+ for SharePoint/OneDrive, Teams Premium for meeting transcripts)
- Global Administrator or Cloud Application Administrator role to:
- Create App Registrations
- Grant application permissions
- Provide admin consent
- Certificate for authentication - See Certificate Generation Guide below
Atolio Environment
- Active Atolio deployment - Contact your Atolio onboarding team if you need assistance
- Configuration values - You’ll collect these from Azure and provide them to your Atolio support contact
Certificate Generation
Microsoft Graph API requires certificate-based authentication. Choose one option:
Option 1: Self-Signed Certificate (OpenSSL)
# Generate private key and certificate
openssl req -x509 -newkey rsa:2048 -keyout atolio-key.pem -out atolio-cert.pem -days 365 -nodes
# Create PFX file (no password)
openssl pkcs12 -export -out atolio-cert.pfx -inkey atolio-key.pem -in atolio-cert.pem -passout pass:
# Create CER file for Azure upload
openssl x509 -outform der -in atolio-cert.pem -out atolio-cert.cer
# Get base64-encoded PFX for Atolio configuration
cat atolio-cert.pfx | base64
Option 2: Self-Signed Certificate (PowerShell/Windows)
# Generate certificate
$cert = New-SelfSignedCertificate -Subject "CN=Atolio" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature
# Export CER file for Azure
Export-Certificate -Cert $cert -FilePath "atolio-cert.cer"
# Export PFX file for Atolio (replace 'password' with your preferred password)
Export-PfxCertificate -Cert $cert -FilePath "atolio-cert.pfx" -Password (ConvertTo-SecureString -String "password" -Force -AsPlainText)
# Get base64-encoded PFX
[Convert]::ToBase64String([IO.File]::ReadAllBytes("atolio-cert.pfx"))
Common Setup Steps
All Microsoft connectors require these foundational steps:
- Create App Registration - Follow Entra ID - Create New App Registration
- Upload Certificate - Add your
.cer
file to the App Registration - Grant API Permissions - Add Application permissions (not Delegated) for each source:
- Admin Consent - Click “Grant admin consent” in the API permissions page
Configuration Values
Collect these values from Azure and provide them to your Atolio support contact:
ClientCert
- Base64-encoded content of the .PFX
file (from certificate generation step)ClientCertPassword
- Certificate’s private key password (if you set one)TenantId
- Directory (tenant) ID from the App Registration Overview pageClientId
- Application (client) ID from the App Registration Overview page
Resource Filtering
All Microsoft connectors support filtering to limit indexing scope using YAML configuration in your connector settings:
resources:
user:
included:
- arthur.dent@example.com
group:
excluded:
- contractors@example.com
Common filter types include:
- User filters - Index content for specific user accounts
- Group filters - Index content accessible by specific Microsoft 365 groups
- LDAP group filters - Index content for members of specific Entra ID security/distribution groups (Outlook only)
- Site/Team filters - Index specific SharePoint sites or Teams
For detailed filtering options, see the individual connector documentation pages.
1 - OneDrive Connector Setup
Provide necessary API permissions to index OneDrive files.
Index OneDrive files by creating a dedicated App Registration with the appropriate permissions.
Setup Checklist
Before starting, ensure you have:
Required API Permissions
Step 1: Create App Registration
- Navigate to Azure Portal > App Registrations
- Click “New registration”
- Enter name:
Atolio OneDrive
- Select “Accounts in this organizational directory only”
- Click “Register”
Step 2: Add API Permissions
⚠️ Important: Only add Application permissions, not Delegated permissions
- In your App Registration, click “API permissions” in the left menu
- Click “Add a permission”
- Select “Microsoft Graph”
- Click “Application permissions” (not Delegated permissions)
Add these Microsoft Graph permissions:
Identity & Directory Permissions (Required for ACL mapping)
Application.Read.All
Group.Read.All
GroupMember.Read.All
User.Read.All
Directory.Read.All
(optional - can omit with disable_full_permissions: true
in configuration)
OneDrive Content Permissions
Step 3: Grant Admin Consent
- After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
- Confirm by clicking “Yes”
- Verify all permissions show “Granted for [your tenant name]” with green checkmarks
Step 4: Upload Certificate
- Click “Certificates & secrets” in the left menu
- Click “Upload certificate”
- Select your
.cer
file (not the .pfx
file) - Add description:
Atolio OneDrive Authentication
- Click “Add”
Step 5: Collect Configuration Values
From the “Overview” page, copy:
- Application (client) ID
- Directory (tenant) ID
You’ll provide these along with your base64-encoded .pfx
certificate to your Atolio support contact.
Resource Filtering
Limit indexing scope using resource filters. OneDrive supports multiple filter types:
User Filtering
Index OneDrive files for specific user accounts:
resources:
user:
included:
- arthur.dent@example.com
- ford.prefect@example.com
excluded:
- galactic-president@example.com
Group Filtering
Index OneDrive files accessible by Microsoft 365 groups:
resources:
group:
included:
- engineering-group@example.com
excluded:
- contractors@example.com
Sample Configuration
Here’s a complete YAML configuration example for OneDrive:
connector: microsoft
source: onedrive
common:
enabled: true
identity-provider: false
cron-spec: "10 */1 * * *"
secrets:
client_cert:
value: "<BASE64_ENCODED_PFX_CONTENT>"
client_cert_password:
value: "<CERTIFICATE_PASSWORD>" # Optional if no password set
configuration:
client-id: "<APPLICATION_CLIENT_ID>"
tenant-id: "<DIRECTORY_TENANT_ID>"
disable_full_permissions: false
resources:
user:
included:
- john.doe@contoso.com
- jane.smith@contoso.com
group:
excluded:
- contractors@contoso.com
Troubleshooting
Error | Cause | Solution |
---|
401 Unauthorized | Missing admin consent | Click “Grant admin consent” in API permissions |
403 Forbidden | Wrong permission type | Ensure you added Application permissions, not Delegated |
invalid_client | Certificate not found/expired | Verify certificate is uploaded and valid |
OneDrive files not appearing | Missing Files.Read.All permission | Add permission and re-grant admin consent |
User drives missing | User not in included list | Check user filtering configuration |
2 - Outlook Connector Setup
Provide necessary API permissions to index Outlook emails and calendar events.
Index Outlook emails and events by creating a dedicated App Registration with the appropriate permissions.
Setup Checklist
Before starting, ensure you have:
Required API Permissions
Step 1: Create App Registration
- Navigate to Azure Portal > App Registrations
- Click “New registration”
- Enter name:
Atolio Outlook
- Select “Accounts in this organizational directory only”
- Click “Register”
Step 2: Add API Permissions
⚠️ Important: Only add Application permissions, not Delegated permissions
- In your App Registration, click “API permissions” in the left menu
- Click “Add a permission”
- Select “Microsoft Graph”
- Click “Application permissions” (not Delegated permissions)
Add these Microsoft Graph permissions:
Identity & Directory Permissions (Required for ACL mapping)
Application.Read.All
Group.Read.All
GroupMember.Read.All
User.Read.All
Directory.Read.All
(optional - can omit with disable_full_permissions: true
in configuration)
Outlook Content Permissions
Mail.Read
Calendars.Read
MailboxSettings.Read
Domain.Read.All
Step 3: Grant Admin Consent
- After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
- Confirm by clicking “Yes”
- Verify all permissions show “Granted for [your tenant name]” with green checkmarks
Step 4: Upload Certificate
- Click “Certificates & secrets” in the left menu
- Click “Upload certificate”
- Select your
.cer
file (not the .pfx
file) - Add description:
Atolio Outlook Authentication
- Click “Add”
Step 5: Collect Configuration Values
From the “Overview” page, copy:
- Application (client) ID
- Directory (tenant) ID
You’ll provide these along with your base64-encoded .pfx
certificate to your Atolio support contact.
Resource Filtering
Limit indexing scope using resource filters. Outlook supports multiple filter types:
User Filtering
Index mailboxes for specific user accounts:
resources:
user:
included:
- arthur.dent@example.com
- ford.prefect@example.com
excluded:
- galactic-president@example.com
LDAP Group Filtering
Index mailboxes for members of Entra ID security/distribution groups:
resources:
ldap:
included:
- f47ed439-7c7d-430d-aff3-0acecdec2cae # Engineering Security Group (ObjectId)
LDAP Group Filter Notes:
- Accepts Entra ID group ObjectIds (GUIDs) or distinguished names
- Filters based on transitive group membership
- Only indexes mailboxes of group members
- Only a single LDAP group filter is supported at a time
- Use Azure AD PowerShell or Graph Explorer to find group ObjectIds
Manually Specify Email Address Domains
If email address domains of your organization are already listed in MS Graph API /domains
query, you can skip this step.
For Atolio to identify contributors of Outlook resources correctly, a list of email address domains must be known. If users in your organization have email addresses like user1@example.com
and user2@contoso.com
, this list should consist of example.com
, and contoso.com
.
You can manually specify an email address domain list as part of your configuration in the following format:
known-domains:
- example.com
- contoso.com
Sample Configuration
Here’s a complete YAML configuration example for Outlook:
connector: microsoft
source: outlook
common:
enabled: true
identity-provider: false
cron-spec: "20 */1 * * *"
secrets:
client_cert:
value: "<BASE64_ENCODED_PFX_CONTENT>"
client_cert_password:
value: "<CERTIFICATE_PASSWORD>" # Optional if no password set
configuration:
client-id: "<APPLICATION_CLIENT_ID>"
tenant-id: "<DIRECTORY_TENANT_ID>"
disable_full_permissions: false
disable-attachments: true # Set to false to index email attachments
backfill-start-time: "2025-01-01T00:00:00Z" # Index emails from this date
known-domains:
- contoso.com
- example.com
resources:
user:
included:
- arthur.dent@example.com
- ford.prefect@example.com
ldap:
included:
- f47ed439-7c7d-430d-aff3-0acecdec2cae # Atolio Users Group
Troubleshooting
Error | Cause | Solution |
---|
401 Unauthorized | Missing admin consent | Click “Grant admin consent” in API permissions |
403 Forbidden | Wrong permission type | Ensure you added Application permissions, not Delegated |
invalid_client | Certificate not found/expired | Verify certificate is uploaded and valid |
Mailboxes not appearing | Missing mail permissions | Verify Mail.Read and Calendars.Read permissions |
LDAP filtering not working | Invalid group ObjectId | Use Azure AD PowerShell to verify group ID |
Contributor identification issues | Missing known-domains | Add all organization email domains to configuration |
3 - SharePoint Connector Setup
Provide necessary API permissions to index SharePoint sites.
Index SharePoint sites, pages, and files by creating a dedicated App Registration with the appropriate permissions.
Setup Checklist
Before starting, ensure you have:
Required API Permissions
Step 1: Create App Registration
- Navigate to Azure Portal > App Registrations
- Click “New registration”
- Enter name:
Atolio SharePoint
- Select “Accounts in this organizational directory only”
- Click “Register”
Step 2: Add API Permissions
⚠️ Important: Only add Application permissions, not Delegated permissions
- In your App Registration, click “API permissions” in the left menu
- Click “Add a permission”
- Select “Microsoft Graph”
- Click “Application permissions” (not Delegated permissions)
Add these Microsoft Graph permissions:
Identity & Directory Permissions (Required for ACL mapping)
Application.Read.All
Group.Read.All
GroupMember.Read.All
User.Read.All
Directory.Read.All
(optional - can omit with disable_full_permissions: true
in configuration)
SharePoint Content Permissions
Files.Read.All
Sites.Read.All
Step 3: Grant Admin Consent
- After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
- Confirm by clicking “Yes”
- Verify all permissions show “Granted for [your tenant name]” with green checkmarks
Step 4: Upload Certificate
- Click “Certificates & secrets” in the left menu
- Click “Upload certificate”
- Select your
.cer
file (not the .pfx
file) - Add description:
Atolio SharePoint Authentication
- Click “Add”
Step 5: Collect Configuration Values
From the “Overview” page, copy:
- Application (client) ID
- Directory (tenant) ID
You’ll provide these along with your base64-encoded .pfx
certificate to your Atolio support contact.
SharePoint Site Groups & Associated Permissions
Many SharePoint sites are deployed without connecting to Microsoft Office 365 groups. Microsoft treats certain SharePoint configurations as unsupported unless managed through Office 365 groups. For Atolio to index correct permissions on non-O365 managed sites, the Sites.FullControl.All
permission is required. Communication Sites commonly fall into this category. For more information on connecting sites to O365 groups, see Microsoft’s documentation.
Atolio can index these sites if Sites.FullControl.All
permission is set on your App Registration. This is the least privileged permission available for read access to the SharePoint API. Atolio never writes back to the SharePoint API.
When configuring the connector for non-O365 group sites:
- Set
Sites.FullControl.All
permissions on the App Registration, specifically within the SharePoint API. (see below screenshot) - Set
IndexSharePointPermissions
configuration to true

All other configuration and certificates remain the same.
Resource Filtering
Limit indexing scope using resource filters. SharePoint supports site-specific filtering:
Site Filtering
Index specific SharePoint sites by URL:
resources:
site:
included:
- https://contoso.sharepoint.com/sites/Engineering
- https://contoso.sharepoint.com/sites/Marketing
excluded:
- https://contoso.sharepoint.com/sites/Confidential
Sample Configuration
Here’s a complete YAML configuration example for SharePoint:
connector: microsoft
source: sharepoint
common:
enabled: true
identity-provider: false
cron-spec: "30 */1 * * *"
secrets:
client_cert:
value: "<BASE64_ENCODED_PFX_CONTENT>"
client_cert_password:
value: "<CERTIFICATE_PASSWORD>" # Optional if no password set
configuration:
client-id: "<APPLICATION_CLIENT_ID>"
tenant-id: "<DIRECTORY_TENANT_ID>"
disable_full_permissions: false
index_sharepoint_permissions: true # Required for non-O365 group sites
resources:
site:
included:
- https://contoso.sharepoint.com/sites/Engineering
- https://contoso.sharepoint.com/sites/Marketing
Troubleshooting
Error | Cause | Solution |
---|
401 Unauthorized | Missing admin consent | Click “Grant admin consent” in API permissions |
403 Forbidden | Wrong permission type | Ensure you added Application permissions, not Delegated |
invalid_client | Certificate not found/expired | Verify certificate is uploaded and valid |
Sites not appearing | Missing Sites.FullControl.All | Add SharePoint API permission for non-O365 group sites |
Permission errors on specific sites | Site not connected to O365 group | Set index_sharepoint_permissions: true |
4 - Teams Connector Setup
Provide necessary API permissions to index Teams channels.
Index Teams channels, chat, messages, and meeting transcripts by creating a dedicated App Registration with the appropriate permissions.
Setup Checklist
Before starting, ensure you have:
Required API Permissions
Step 1: Create App Registration
- Navigate to Azure Portal > App Registrations
- Click “New registration”
- Enter name:
Atolio Teams
- Select “Accounts in this organizational directory only”
- Click “Register”
Step 2: Add API Permissions
⚠️ Important: Only add Application permissions, not Delegated permissions
- In your App Registration, click “API permissions” in the left menu
- Click “Add a permission”
- Select “Microsoft Graph”
- Click “Application permissions” (not Delegated permissions)
Add these Microsoft Graph permissions:
Identity & Directory Permissions (Required for ACL mapping)
Application.Read.All
Group.Read.All
GroupMember.Read.All
User.Read.All
Directory.Read.All
(optional - can omit with disable_full_permissions: true
in configuration)
Teams Content Permissions
Channel.ReadBasic.All
ChannelMember.Read.All
ChannelMessage.Read.All
Chat.Read.All
ChatMember.Read.All
ChatMessage.Read.All
Team.ReadBasic.All
TeamMember.Read.All
Teams Meeting Transcripts (Optional)
OnlineMeetings.Read.All
OnlineMeetingTranscript.Read.All
Calendars.Read
Domain.Read.All
Step 3: Grant Admin Consent
- After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
- Confirm by clicking “Yes”
- Verify all permissions show “Granted for [your tenant name]” with green checkmarks
Step 4: Upload Certificate
- Click “Certificates & secrets” in the left menu
- Click “Upload certificate”
- Select your
.cer
file (not the .pfx
file) - Add description:
Atolio Teams Authentication
- Click “Add”
Step 5: Collect Configuration Values
From the “Overview” page, copy:
- Application (client) ID
- Directory (tenant) ID
You’ll provide these along with your base64-encoded .pfx
certificate to your Atolio support contact. This link is beside the Add a permission
link.
Application Access Policy for Teams Meeting Transcripts
In addition to Entra ID permissions above, you need to setup an application access policy for Atolio to access transcripts.
- Open PowerShell. Install the Microsoft Teams PS module:
Install-Module -Name MicrosoftTeams -Force -AllowClobber
- Connect to Teams module w/ an admin account on your shell. This will prompt a login page on your browser:
Import-Module MicrosoftTeams
Connect-MicrosoftTeams
- Create a new policy. Assuming the policy name is “Atolio-Transcript-Access-Policy”, and the previously registered application ID (client ID) is “some-app-id”, the shell command will be as follows:
New-CsApplicationAccessPolicy -Identity Atolio-Transcript-Access-Policy -AppIds "some-app-id" -Description "Access policy for teams transcripts"
- Associate users with the policy. You have two options:
- Option 1 - Grant tenant-wide access (recommended). This will allow Atolio to index transcripts owned by every user who does not have an application access policy assigned:
Grant-CsApplicationAccessPolicy -PolicyName Atolio-Transcript-Access-Policy -Global
- Option 2 - Grant user-specific access. This will allow Atolio to index transcripts owned by explicitly declared users only:
Grant-CsApplicationAccessPolicy -PolicyName Atolio-Transcript-Access-Policy -Identity "some-user-id"
More details about the policy setup can be found in the official documentation:
Resource Filtering
Limit indexing scope using resource filters. Teams supports team-specific filtering:
Team Filtering
Index specific Teams by name or ID:
resources:
team:
included:
- 66e327b3-321a-4ebf-8e2c-34cebf134bf8 # Engineering Team ID
- 0507654f-506d-4805-95d5-516bcaf1075c # Sales Team ID
excluded:
- b0b083d0-6288-45ce-8ecd-16960ba7b329 # HR Team ID
Sample Configuration
Here’s a complete YAML configuration example for Teams:
connector: microsoft
source: teams
common:
enabled: true
identity-provider: false
cron-spec: "40 */1 * * *"
secrets:
client_cert:
value: "<BASE64_ENCODED_PFX_CONTENT>"
client_cert_password:
value: "<CERTIFICATE_PASSWORD>" # Optional if no password set
configuration:
client-id: "<APPLICATION_CLIENT_ID>"
tenant-id: "<DIRECTORY_TENANT_ID>"
disable_full_permissions: false
enable-transcripts: true # Enable meeting transcript indexing
skip-chats: false # Set to true to skip private chats
resources:
team:
included:
- 66e327b3-321a-4ebf-8e2c-34cebf134bf8 # Engineering Team ID
- 0507654f-506d-4805-95d5-516bcaf1075c # Marketing Team ID
Troubleshooting
Error | Cause | Solution |
---|
401 Unauthorized | Missing admin consent | Click “Grant admin consent” in API permissions |
403 Forbidden | Wrong permission type | Ensure you added Application permissions, not Delegated |
invalid_client | Certificate not found/expired | Verify certificate is uploaded and valid |
Teams not appearing | Missing team permissions | Verify all Teams permissions are granted |
Transcripts missing | Application access policy not set | Follow PowerShell policy setup steps above |
Private chats missing | Chat.Read.All permission missing | Add permission and re-grant admin consent |
Limitations
- Only first 1000 replies to a channel post will be indexed, due to limitations with the Microsoft API.