Managing Exchange Service Accounts (admins.json)

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

Step 1. Create the Directory and JSON File

Pro Tip

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 will be placed, 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

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.

Example 1: Single Administrator (Cloud / Microsoft 365)

For the Cloud Exchange type, the Service__ExchangeConfiguration__ExchangeType=parameter in .env should be set to 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)

For the On-Premise Kerberos Exchange type, the Service__ExchangeConfiguration__ExchangeType=parameter in .env should be set to 2.

Use Username and Password for Kerberos environments.

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

Example 3: Multiple Administrators (On-Premise BasicAuth)

For the On-Premise BasicAuth Exchange type, the Service__ExchangeConfiguration__ExchangeType= varaible in .env should be set to 3.

Use Username and Password for BasicAuth environments.

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

Example 4: Multiple Administrators (On-Premise ADFS)

For the On-Premise ADFS Exchange type, the Service__ExchangeConfiguration__ExchangeType=parameter in .env should be set to 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)

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.

By default, the application will automatically look for an admins.json file in the exchangeAdmins directory. You only need to configure the path if you are using custom subfolders or filenames.

Example direct pointing to the exchangeAdmins folder:

Service__ExchangeConfiguration__ExchangeAdminFile=

Example pointing to a custom subfolder (e.g., exchangeAdmins/prod):

Service__ExchangeConfiguration__ExchangeAdminFile=prod/admins.json

Next Step

Deploying via Docker (Single Instance)