Managing Exchange Service Accounts

This guide explains how to securely configure and manage Microsoft Exchange administrator credentials for the Nextcloud Exchange Connector.

Note: Using an external JSON file (admins.json) is the official and most scalable method to authenticate your application with Microsoft Exchange, allowing you to bypass performance bottlenecks and easily manage multiple environments.

Why the application requires a JSON array of accounts rather than a single hardcoded username and password?

Microsoft Exchange enforces strict throttling limits per identity, such as a maximum number of concurrent Exchange Web Services (EWS) connections and subscriptions. In older versions of the connector, using a single hardcoded administrator account created a massive bottleneck, severely slowing down the synchronization process for large user bases.

By defining an array of multiple service accounts, the connector automatically distributes mailbox operations across them. Because each account has its own independent throttling budget, this approach effectively multiplies your available throughput and prevents any single identity from hitting its limit.

Step 1. Create the Directory and JSON File

Why this is needed: To isolate sensitive credentials from your main .env configuration file and establish a flexible folder structure for different environments.

The connector supports a highly flexible directory structure for your credentials. You can organize multiple JSON files in custom subfolders (e.g., separating test accounts from production accounts) and switch between them by simply updating a single path in your .env file.

Create a base directory named exchangeAdmins in the same location as your deployment files, and create your JSON file inside it:

# Create the directory
mkdir exchangeAdmins
 
# Create the JSON file (you can name it admins.json, testAdmins.json, etc.)
touch exchangeAdmins/admins.json

Step 2. Format the Credentials Payload

Why this is needed: The connector requires a specific JSON array structure depending on your Exchange authentication type (Cloud, On-Premise Kerberos/Basic, or ADFS).

Below are examples of how to format your admins.json file. You can configure a single administrator or multiple administrators to increase parallel processing capacity.

Warning: Do Not Mix Exchange Types

You cannot mix different Exchange connection types (e.g., placing one Cloud account and one On-Premise account) in the same admins.json file. The application initializes the client connection only once per instance. Mixing account types will break the application and cause specific accounts to fail.

Warning: The "ExchangeType" Field is a Comment

The "ExchangeType" field inside the JSON payload is not an active configuration parameter; it acts purely as a visual comment for the administrator. The actual connection type is dictated strictly by the Service__ExchangeConfiguration__ExchangeType parameter in your .env file.

Example 1: Single Administrator (Cloud / Microsoft 365 Service__ExchangeConfiguration__ExchangeType=1)

Use AppId and ClientSecret for Cloud environments.

[
  {
    "AppId": "your-app-id-1",
    "ClientSecret": "your-client-secret-1"
  }
]

Example 2: Multiple Administrators (On-Premise Kerberos Service__ExchangeConfiguration__ExchangeType=2 / BasicAuth Service__ExchangeConfiguration__ExchangeType=3)

Use User and Pass (or Username and Password) for On-Premise environments.

[
  {
    "Username": "serviceaccount-1",
    "Password": "your-password-1"
  },
  {
    "Username": "serviceaccount-2",
    "Password": "your-password-2"
  }
]

Example 3: Multiple Administrators (On-Premise ADFS Service__ExchangeConfiguration__ExchangeType=4)

Use ClientId and ClientSecret for ADFS environments.

[
  {
    "ClientId": "your-client-id-1",
    "ClientSecret": "your-client-secret-1"
  },
  {
    "ClientId": "your-client-id-2",
    "ClientSecret": "your-client-secret-2"
  }
]

Step 3. Link the File in your Configuration (.env)

Why this is needed: To explicitly tell the Nextcloud Exchange Connector where to find your credentials payload.

Open your .env configuration file and update the Service__ExchangeConfiguration__ExchangeAdminFile parameter with the relative path to your JSON file.

Note:
The application uses a fallback mechanism: it will first try to read the custom path you provide in the Service__ExchangeConfiguration__ExchangeAdminFile parameter.

If it fails or the file is missing, it will look for a default admins.json.

Example direct pointing to the exchangeAdmins folder:

Service__ExchangeConfiguration__ExchangeAdminFile=admins.json

Example pointing to a custom subfolder:

Service__ExchangeConfiguration__ExchangeAdminFile=prod/admins.json

Warning: Avoid ExchangeAdminRaw

Older setups allowed passing the JSON string directly into the .env file using the Service__ExchangeConfiguration__ExchangeAdminRaw variable. This approach is highly discouraged. Escaping quotes (") and slashes (\) within environment variables is difficult and causes the JSON parser to fail.

Always use the ExchangeAdminFile approach.