Understanding the Architecture

This article provides a high-level understanding of the application's architecture, its internal synchronization engine, and its deployment topologies.

Architecture & Protocol Translation

At its core, the connector acts as a bidirectional protocol translator. Nextcloud natively relies on open standards: CalDAV for calendars and tasks, and CardDAV for contacts. In contrast, Microsoft Exchange utilizes its proprietary Exchange Web Services (EWS).

The synchronization ecosystem is divided into two distinct components to handle this translation:

1. The Nextcloud App (Frontend): A lightweight Nextcloud application that provides the User Consent UI and exposes dedicated API endpoints. It serves as an authentication gateway.

2. The Connector Daemon (Backend): A worker service that runs entirely independently of the Nextcloud web server. It fetches EWS payloads from Microsoft, maps the data properties into standard CalDAV (V-Calendar) and CardDAV (V-Card) formats, and pushes them to the Nextcloud App API (and vice versa).

This decoupled architecture ensures that heavy synchronization loads and payload translations do not impact Nextcloud's web performance.

Authentication & Security Model

The connector employs a dual-authentication strategy:

• Nextcloud Side: The worker authenticates against the Nextcloud API using a dedicated service account and an App Password. All webhook and API communication between the Nextcloud frontend and the worker is cryptographically secured using a pre-configured SharedSecret.

• Exchange Side: The application operates as a background daemon using Microsoft's delegated access models.

  • For On-Premise environments (Exchange 2016, 2019, and Subscription Edition), it uses ApplicationImpersonation via Kerberos or Basic Authentication.

  • For Microsoft 365 (Cloud), it uses OAuth 2.0 app-only authentication with the full_access_as_app permission. This allows the system to read and write to user mailboxes based strictly on their backend identifiers.

• User Identity Matching: When the connector synchronizes data, the backend locates a user's Exchange mailbox strictly based on their primary email address. The email address associated with the user's Nextcloud account must perfectly match their primary SMTP address in Microsoft Exchange for the delegated access to succeed.

The Synchronization Engine & Throttling

The core of the daemon is governed by configurable polling intervals (SyncIntervalInSeconds and CriticalSyncIntervalInSeconds). The engine fetches user states, processes them in manageable batches (BatchLimit, BatchSaveSize), and executes the payload mapping between EWS and CalDAV/CardDAV.

To scale efficiently and distribute synchronization loads, the architecture features a Connection Pool configured via an external JSON file. By defining an array of service accounts in the admins.json file, the worker dynamically distributes EWS sessions across multiple administrator identities. This maximizes the available throughput, which can be fine-tuned using the MaxParallelProcessingUsers and MaxUsersPerAdmin parameters.

[
  {
    "Username": "sync-admin-1",
    "Password": "PasswordA!"
  },
  {
    "Username": "sync-admin-2",
    "Password": "PasswordB!"
  }
]

Sync Modes & Bitwise Configuration

Administrators control exactly which CalDAV/CardDAV objects flow through the connector using bitwise masks in the .env file. The Service__SyncMode parameter calculates the active features by summing the following base values:

• 0 = None

• 1 = Calendars (CalDAV)

• 2 = Contacts (CardDAV)

To synchronize both Calendars and Contacts, the administrator sets the value to 3 (1 + 2).

Additionally, the Service__SyncType parameter dictates the data privacy level:

• 0 (Full): Synchronizes all event details (Titles, Descriptions, Attendees). This is the default setting.

• 1 (Sensitive): Masks all private event details, synchronizing only the time block with a placeholder title (configurable via SensitiveTitle, usually "Busy").

# Example: Synchronizing Calendars and Contacts in Sensitive Mode
Service__SyncMode=3
Service__SyncType=1
Service__SensitiveSyncConfiguration__SensitiveTitle="Busy"

Logging Architecture

The connector employs a flexible, asynchronous logging architecture. Administrators can route diagnostic data to multiple destinations depending on their infrastructure needs.

For a comprehensive guide on the available options, please refer to the Logging & Monitoring [TO INSERT THE SUBCATEGORY LINK HERE AFTER FULL DOCUMENTATION APPROVAL].

Deployment Topologies

The microservice is designed to be highly versatile and supports two primary deployment topologies:

1. Containerized (Docker): The preferred method for scalable environments. Using docker-compose, administrators can easily spin up the application alongside its database and logging stack. The variable Secondary_Replicas_Amount allows Docker to auto-scale multiple worker containers that share the load via the common database.

2. Binary Installation: For environments that do not support containerization, the pre-compiled binaries can be executed directly on the host OS.

Next Step

Configuring Microsoft 365 (Cloud) OR Configuring Exchange On-Premise