This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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:

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:

  1. Create App Registration - Follow Entra ID - Create New App Registration
  2. Upload Certificate - Add your .cer file to the App Registration
  3. Grant API Permissions - Add Application permissions (not Delegated) for each source:
  4. 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 page
  • ClientId - 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:

  • Azure Global Administrator or Cloud Application Administrator role
  • Microsoft 365 E1+ licensing for OneDrive content
  • Certificate generated (see Certificate Generation Guide)
  • Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

  1. Navigate to Azure Portal > App Registrations
  2. Click “New registration”
  3. Enter name: Atolio OneDrive
  4. Select “Accounts in this organizational directory only”
  5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

  1. In your App Registration, click “API permissions” in the left menu
  2. Click “Add a permission”
  3. Select “Microsoft Graph”
  4. 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

  • Files.Read.All
  1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
  2. Confirm by clicking “Yes”
  3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

  1. Click “Certificates & secrets” in the left menu
  2. Click “Upload certificate”
  3. Select your .cer file (not the .pfx file)
  4. Add description: Atolio OneDrive Authentication
  5. 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

ErrorCauseSolution
401 UnauthorizedMissing admin consentClick “Grant admin consent” in API permissions
403 ForbiddenWrong permission typeEnsure you added Application permissions, not Delegated
invalid_clientCertificate not found/expiredVerify certificate is uploaded and valid
OneDrive files not appearingMissing Files.Read.All permissionAdd permission and re-grant admin consent
User drives missingUser not in included listCheck 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:

  • Azure Global Administrator or Cloud Application Administrator role
  • Microsoft 365 licensing for Outlook content
  • Certificate generated (see Certificate Generation Guide)
  • Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

  1. Navigate to Azure Portal > App Registrations
  2. Click “New registration”
  3. Enter name: Atolio Outlook
  4. Select “Accounts in this organizational directory only”
  5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

  1. In your App Registration, click “API permissions” in the left menu
  2. Click “Add a permission”
  3. Select “Microsoft Graph”
  4. 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
  1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
  2. Confirm by clicking “Yes”
  3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

  1. Click “Certificates & secrets” in the left menu
  2. Click “Upload certificate”
  3. Select your .cer file (not the .pfx file)
  4. Add description: Atolio Outlook Authentication
  5. 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

ErrorCauseSolution
401 UnauthorizedMissing admin consentClick “Grant admin consent” in API permissions
403 ForbiddenWrong permission typeEnsure you added Application permissions, not Delegated
invalid_clientCertificate not found/expiredVerify certificate is uploaded and valid
Mailboxes not appearingMissing mail permissionsVerify Mail.Read and Calendars.Read permissions
LDAP filtering not workingInvalid group ObjectIdUse Azure AD PowerShell to verify group ID
Contributor identification issuesMissing known-domainsAdd 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:

  • Azure Global Administrator or Cloud Application Administrator role
  • Microsoft 365 E1+ licensing for SharePoint content
  • Certificate generated (see Certificate Generation Guide)
  • Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

  1. Navigate to Azure Portal > App Registrations
  2. Click “New registration”
  3. Enter name: Atolio SharePoint
  4. Select “Accounts in this organizational directory only”
  5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

  1. In your App Registration, click “API permissions” in the left menu
  2. Click “Add a permission”
  3. Select “Microsoft Graph”
  4. 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
  1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
  2. Confirm by clicking “Yes”
  3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

  1. Click “Certificates & secrets” in the left menu
  2. Click “Upload certificate”
  3. Select your .cer file (not the .pfx file)
  4. Add description: Atolio SharePoint Authentication
  5. 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

sharepoint permissions

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

ErrorCauseSolution
401 UnauthorizedMissing admin consentClick “Grant admin consent” in API permissions
403 ForbiddenWrong permission typeEnsure you added Application permissions, not Delegated
invalid_clientCertificate not found/expiredVerify certificate is uploaded and valid
Sites not appearingMissing Sites.FullControl.AllAdd SharePoint API permission for non-O365 group sites
Permission errors on specific sitesSite not connected to O365 groupSet 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:

  • Azure Global Administrator or Cloud Application Administrator role
  • Teams Premium licensing (for meeting transcripts)
  • Certificate generated (see Certificate Generation Guide)
  • Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

  1. Navigate to Azure Portal > App Registrations
  2. Click “New registration”
  3. Enter name: Atolio Teams
  4. Select “Accounts in this organizational directory only”
  5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

  1. In your App Registration, click “API permissions” in the left menu
  2. Click “Add a permission”
  3. Select “Microsoft Graph”
  4. 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
  1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
  2. Confirm by clicking “Yes”
  3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

  1. Click “Certificates & secrets” in the left menu
  2. Click “Upload certificate”
  3. Select your .cer file (not the .pfx file)
  4. Add description: Atolio Teams Authentication
  5. 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

ErrorCauseSolution
401 UnauthorizedMissing admin consentClick “Grant admin consent” in API permissions
403 ForbiddenWrong permission typeEnsure you added Application permissions, not Delegated
invalid_clientCertificate not found/expiredVerify certificate is uploaded and valid
Teams not appearingMissing team permissionsVerify all Teams permissions are granted
Transcripts missingApplication access policy not setFollow PowerShell policy setup steps above
Private chats missingChat.Read.All permission missingAdd 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.