Outlook Connector Setup

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)

Outlook Content Permissions

• Mail.Read
• Calendars.Read
• MailboxSettings.Read
• Domain.Read.All

Step 3: Grant Admin Consent

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 and its password, as listed in Required Configuration Values.

Required Configuration Values

Enter these values in the Atolio Admin console (v4.24 and later), or send them to Atolio Support (your Deployment Engineer).

Keep secrets secure: Share values marked “Yes” in the Secret column only through a password-manager share (e.g. 1Password) or another secure channel agreed with Atolio Support. Never send them in plain email, chat, or support tickets.

Configuration Example

Add this block to connector-values.yaml. Replace each <PLACEHOLDER> with the matching value from the table above, and remove any line marked “Only if” that doesn’t apply.

connectors:
  microsoft:
    default:
      outlook:
        connector: microsoft
        instance: default
        source: outlook
        common:
          enabled: true
          identity-provider: false
        secrets:
          client_cert:
            value: "<BASE64_PFX_CERTIFICATE>"
          client_cert_password:
            value: "<PFX_PASSWORD>"
        configuration:
          tenant-id: "<DIRECTORY_TENANT_ID>"
          client-id: "<APPLICATION_CLIENT_ID>"
          known-domains:  # Only if your domains aren't returned by the Microsoft Graph /domains query
            - "<KNOWN_EMAIL_DOMAIN>"

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

Optional Settings Example

These optional settings go in the same block as the Configuration Example, under common: and configuration:. This example shows optional settings for Outlook, including a sync schedule and resource filters:

common:
  cron-spec: "20 */1 * * *"
configuration:
  disable-attachments: true    # Set to false to index email attachments
  backfill-start-time: "2025-01-01T00:00:00Z"  # Index emails from this date
  resources:
    user:
      included:
        - arthur.dent@example.com
        - ford.prefect@example.com
    ldap:
      included:
        - f47ed439-7c7d-430d-aff3-0acecdec2cae  # Atolio Users Group

Troubleshooting