> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/microsoft/6-exchange.md). # Exchange connector This page describes how to enable provisioning to Exchange and Exchange online The Exchange connector lets OpenIAM manage Exchange mailboxes — creating them, changing their settings, moving addresses, granting mailbox permissions, and suspending or deleting the account behind them. It provisions **user mailboxes**, **room, equipment and shared mailboxes**, and **distribution group membership**. It works against **Exchange on-premises**, **Exchange Online**, and **hybrid** deployments where the account stays in on-premises Active Directory while the mailbox lives online. Moving from one to the next is a change of connector scope, not a new managed system. The connector is a .NET/PowerShell connector: it runs as a Windows service on a host that can reach Exchange, and exchanges requests with OpenIAM over RabbitMQ. | Operation | Supported | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Search / import mailboxes | ✅ | | Create a mailbox | ✅ — part of save, when the identity does not exist yet | | Update a mailbox | ✅ | | Suspend / resume | ✅ | | Delete a mailbox | ✅ | | Reset password | ✅ | | Check a password (Login) | ❌ — refused. Exchange recipients authenticate with their AD or Entra ID account; validate the password against that managed system instead | | Test connection | ✅ | There is no separate create operation. OpenIAM sends a save, and the connector looks the identity up first, creating the mailbox only when it does not find one. ## Use cases * **Giving a joiner a mailbox** during provisioning — either attaching one to the Active Directory account another connector has just created, or creating the account and its mailbox together. * **Keeping mail attributes in step with HR data** — display name, SMTP addresses, retention and ActiveSync policies, distribution group membership. * **Moving from on-premises Exchange to Exchange Online**, where the managed system survives the move and only the connector scope changes. ## Versions and compatibility | Target | What the connector supports | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Exchange Server** | 2010 and later. Two attributes, `ManagedFolderMailboxPolicy` and `ManagedFolderMailboxPolicyAllowed`, apply only to Exchange 2010 | | **Exchange Online** | Current. The connector host needs the `ExchangeOnlineManagement` PowerShell module | | **Hybrid** | An on-premises Exchange server exposing the `*-RemoteMailbox` cmdlets | Which one the connector targets is set by `ConnectorModeSettings` — see [Connector scope](#connector-scope). ## Prerequisites * The Exchange server is reachable from the machine running the connector, and a remote PowerShell session to it is possible. * A service account holding the rights for the operations you intend to perform. * For **Exchange Online**: the `ExchangeOnlineManagement` PowerShell module on the connector host and, if you authenticate as an application rather than with a password, a certificate and an Azure app registration — see [Application authentication](#application-authentication-exchange-online). * The requirements shared by all .NET/PowerShell connectors, in [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). When configuring the Managed System in the OpenIAM Webconsole, specify the **Login ID** for the service account. Exchange uses an AD account to perform mailbox operations. {% hint style="info" %} The service account must include the domain name, for example: `openiamtest\serviceAccount`. {% endhint %} ## Installing the connector Every .NET/PowerShell connector installs the same way, this one included. See [PowerShell connector installation](/connector-configuration/microsoft/1-powershellconnectorinstallation.md) for the hardware and software requirements, the installer itself, running several connectors on one host, load balancing, and removing or updating an installation. ## Starting, stopping, and restarting The installer registers **two Windows services**, each suffixed with the connector name you give during installation: | Service | Display name | What it does | | -------------------------------- | ----------------------------------------- | ---------------------------------------------------------- | | `OpenIAMExchangeConnector` | OpenIAM Exchange ConnectorService \ | Takes requests off RabbitMQ and runs them against Exchange | | `OpenIAMLogService` | OpenIAM Log Service \ | Writes the connector's log database | A connector installed as `Contoso` therefore registers `OpenIAMExchangeConnectorContoso`. Start and stop them as you would any Windows service: {% code overflow="wrap" %} ```powershell Get-Service OpenIAMExchangeConnector* | Restart-Service ``` {% endcode %} The installer starts both services when it finishes, stops them when it upgrades or uninstalls, and removes them on uninstall, so a routine installation needs none of this. {% hint style="info" %} Restart the connector service after editing `Connector.config` by hand — the connector reads its configuration at startup. {% endhint %} ## Command-line parameters and properties The connector takes **no command-line parameters**. It runs as a Windows service, and everything adjustable lives in `Connector.config` in the connector folder: queue names and concurrency, logging level and rotation, simulation mode, warm runner pools, and the TLS settings for RabbitMQ. Those settings are identical across the .NET/PowerShell connectors and are documented once, in [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). ## Verifying the connector is running {% stepper %} {% step %} Confirm both Windows services are running on the connector host. {% endstep %} {% step %} Check that the connector's request queue in RabbitMQ has a consumer. {% endstep %} {% step %} Run **Test Connection** on the managed system in the Webconsole. {% endstep %} {% step %} Run one real operation — a search — to prove the path end to end. {% endstep %} {% endstepper %} Test Connection is a genuine check rather than a ping. Before the connector reaches the test it opens the Exchange session from the managed system's own settings: online that is `Connect-ExchangeOnline` with either the credentials or the application certificate, and on premises or hybrid it is a remote PowerShell session to the host and port you configured. A passing test therefore means the endpoint, the credentials and — with application authentication — the certificate and organization are all good. ## Troubleshooting Connector troubleshooting is covered in the PowerShell connectors usage document: [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md). The steps there apply to all .NET/PowerShell connectors. The table below contains Exchange-specific notes. | Symptom | Likely cause | Resolution | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `The operation couldn't be performed because object 'x' couldn't be found on 'y'` | The distribution group exists in Active Directory but is not visible to Exchange. Groups created through Exchange cmdlets generally are; groups created directly in AD often are not | Confirm the group in the Exchange admin area. If it was created in AD, recreate it through Exchange | | `Please set Organization attribute on the managed system level` | Application authentication needs the tenant's primary domain, and it is not set | Set **Organization** to the primary domain, for example `contosoelectronics.onmicrosoft.com` — see [What to set on the managed system](#what-to-set-on-the-managed-system) | | `Could not establish the Exchange session to …` | The connector failed before any operation ran | Check the host and port on the managed system and the service account. Under application authentication, check the certificate thumbprint and the organization as well | | `… is not supported for Hybrid Exchange`, `… is not implemented for Exchange Online`, `… is not implemented on-premise Exchange` | The operation is not available in the configured connector scope | See [What each scope refuses](#what-each-scope-refuses), then either change the scope or route the operation elsewhere | | `Attribute Name of PrincipalFieldName in Resource Policy Map has invalid value`, `principalProperty can not be null` | The managed system's principal attribute is missing, or is not one the connector can look a mailbox up by | Set the principal attribute to one the connector supports | | `Unknown ConnectorScope` | `connectorScope` in `ConnectorModeSettings` is not one of `premise`, `online` or `hybrid` | Correct the value in `Connector.config` | | `Attribute Password is supposed to be set at Reset-IdentityPassword, but was empty` | A reset password request arrived with no password in the attribute map | Map the password attribute in the policy map | | `Unable to find case sensitive value of identity name` | The identity value does not match a mailbox once case is taken into account | Check the identity value's case against the mailbox | ## Registering the connector in OpenIAM The connector's request queue name in OpenIAM has to match the queue in the connector's own `Connector.config` exactly. Getting the connection parameters out of OpenIAM and into the installer is covered in [PowerShell connector installation](/connector-configuration/microsoft/1-powershellconnectorinstallation.md). ## Configuring the managed system In the Managed System configuration page, specify the service account with sufficient privileges for the intended Exchange mailbox operations.
The Managed System form for the Exchange PowerShell Connector, filled in with a host name, port 80, the CLEAR communication protocol and a domain-qualified Login Id, with Active switched on and Show on User Change Password Screen off
These attributes are set on the managed system rather than per identity: | Attribute | Description | Applies to | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `ConnectorModeSettings` | Selects the connector scope and the user creation behavior. See [Connector scope](#connector-scope). | All scopes | | `SkipCNCheck` | `True` stops the connector checking that the Exchange server's TLS certificate name (CN or SAN) matches the URL it connects to. The certificate chain and expiry are still validated. Set it only when a certificate name mismatch is blocking the session — the connector's error message names this attribute when that is the cause. | `premise`, `hybrid` | | `AppAuth`, `Organization`, `CertificateThumbprint` | Authenticate as an Azure application instead of with a password. See [Application authentication](#application-authentication-exchange-online). | `online` | {% hint style="info" %} **Save the managed system before you go looking for the Attributes panel.** It is not on the creation form. Once the record exists, an **Attributes** panel appears below *Downstream Managed System* — together with **Delete** and **Clone Managed System** — and each attribute is added there with the **+** button, as a name and a value. {% endhint %} ### How the connection is built | Field | What the connector does with it | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Host URL** | The Exchange server. Read in `premise` and `hybrid` scope only — in `online` scope the connector goes to Exchange Online directly and ignores it | | **Port** | Goes into the URL, and **also decides the protocol**: `443` gives `https` with Basic authentication, any other value gives `http` with Kerberos | | **Communication Protocol** | **Nothing — this connector never reads it.** The port decides | | **Login Id** | The service account, domain-qualified | The connector assembles `://:/powershell`. If Host URL already starts with `http://` or `https://` it is taken as given, with the port still appended. {% hint style="warning" %} **Always set Port.** It is concatenated straight into the URL, so an empty Port produces `http://exchange.example.local:/powershell`, which cannot connect. Port 80 is the usual on-premises Exchange remote PowerShell endpoint, and 443 is the one to use for TLS. Because the port alone chooses the protocol, a managed system set to **CLEAR on port 443 still uses TLS**, and one set to **SSL on port 80 does not**. Set the port to the protocol you want. {% endhint %} `SkipCNCheck` only has an effect on an `https` connection, which is to say on port 443. ### Connector scope The `ConnectorModeSettings` attribute controls two parameters: where the mailbox lives, and what an ADD operation creates. **Connector scope** takes one of three values: | Value | Mailbox location | How the connector reaches it | | --------- | --------------------------------------------------- | -------------------------------------------------------------------------------------- | | `premise` | Your Exchange server | A remote PowerShell session to the server, using the `*-Mailbox` cmdlets | | `online` | Exchange Online | A session to Exchange Online, using the `*-Mailbox` cmdlets | | `hybrid` | Exchange Online, with the account in on-premises AD | A session to your **on-premises** Exchange server, using the `*-RemoteMailbox` cmdlets | **User creation behavior** determines what happens on an ADD operation: `enable` attaches a mailbox to an existing AD user, `create` creates a new AD user with a mailbox. The value is a JSON string: {% code overflow="wrap" %} ``` {"connectorScope":"premise","newUserBehavior":"create"} ``` {% endcode %} Set it **on the managed system** — the scope describes the environment, so it is the same for every identity. The connector also accepts it as a user provisioning attribute, and a value there overrides the managed system for that one request. If neither is set, the connector uses **premise** scope and **enable** behavior. #### What each scope refuses The scope decides more than how the connector connects. Several operations are refused outright in one scope or another, each with a message naming the scope, so it is worth knowing before a policy map relies on one: | Operation | Refused in | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | ActiveSync settings | **hybrid** | | Suspend a mailbox | **hybrid** | | Reset a mailbox password | **hybrid**, and in **online** — Exchange Online mailboxes authenticate with their Entra account, so reset it through the Entra connector | | Archive quota | **hybrid** and **online** | | Assign or remove a licence | **hybrid** and **premise** — licensing belongs to the Entra connector | | Distribution group membership | **hybrid** | | Shared mailboxes | **online** | | Room and equipment mailboxes through the **enable** behavior | **online** — use the **create** behavior instead, which provisions the mailbox | | Renaming — changing a mailbox's principal identity | **online** — identity attributes belong to the Entra connector. Rename there, then re-synchronize | {% hint style="info" %} The pattern behind most of these is the same: in hybrid and online deployments the account itself lives in Entra ID, so anything that is really a property of the account rather than of the mailbox — its password, its licence, its name — is the [Microsoft Graph PowerShell connector](/connector-configuration/microsoft/14-psgraph.md)'s job, not this one's. {% endhint %} ## Application authentication (Exchange Online) From version **5.30.1.0**, the Exchange Online connector can authenticate as an **Azure application** holding a certificate, instead of as a service account with a password. Setting the application up is Microsoft's own procedure, and Microsoft keeps it current as the portal changes: [App-only authentication in Exchange Online PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#set-up-app-only-authentication). Work through its five steps, making the choices in the table below, then configure the managed system in OpenIAM. ### What to choose in the Azure portal | Microsoft's step | What to choose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Step 1 — Register the application](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-1-register-the-application-in-microsoft-entra-id) | Any name will do. Note the **Application (client) ID**, which OpenIAM needs | | [Step 2 — Assign API permissions](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-2-assign-api-permissions-to-the-application) | Under **APIs my organization uses**, choose **Office 365 Exchange Online** → **Application permissions** → **Exchange.ManageAsApp**, then grant admin consent | | [Step 3 — Generate a certificate](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-3-generate-a-certificate) | Generate it on the connector machine instead — see below | | [Step 4 — Attach the certificate](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-4-attach-the-certificate-to-the-microsoft-entra-application) | Upload the exported certificate, the copy without the private key. Note its **thumbprint** | | [Step 5 — Assign role permissions](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-5-assign-role-permissions-to-the-application) | Assign the **Exchange Administrator** role to the application | Step 4b covers delegated, multi-tenant scenarios and does not apply to a connector managing a single tenant. After step 5 the application appears under the role as a service principal, which is the quickest confirmation that the Azure side is done:
The Exchange Administrator Assignments list showing the application assigned, with type ServicePrincipal and directory scope
### The certificate Generate the certificate **on the machine running the connector**, so the private key stays there and never travels. Set your own CN, and run this in an **elevated** PowerShell — writing to `Cert:\LocalMachine\My` needs administrator rights and fails silently in an ordinary shell: {% code overflow="wrap" %} ```powershell $certname = "OpenIAM_Exchange" New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\LocalMachine\My" -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -NotAfter (Get-Date).AddYears(10) ``` {% endcode %} Then export it **without the private key** — that copy is what you upload in Microsoft's step 4.
The Certificates snap-in for the local computer, with a certificate selected and the All Tasks submenu open on Export
The Certificate Export Wizard on the Export Private Key page, with No, do not export the private key selected
### What to set on the managed system Set these on the Exchange managed system in the Webconsole: | Attribute | Value | | ----------------------- | ------------------------------------------------------------------------------ | | `AppAuth` | `True` | | `Organization` | Your tenant's primary domain, for example `contosoelectronics.onmicrosoft.com` | | `CertificateThumbprint` | The thumbprint of the certificate uploaded in step 4 | | **Login Id** | The application's **Application (client) ID**, in place of a user name | The connector host also needs the `ExchangeOnlineManagement` PowerShell module — see [Install the Exchange Online PowerShell module](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell-v2?view=exchange-ps#install-the-exchange-online-powershell-module). ## Attribute mapping and policy map The policy map on the managed system decides which OpenIAM identity attributes reach Exchange and under what names. What follows is what the connector does with them once they arrive. ### Creating a mailbox * In **Create + Premise** mode, you must set: * Name * Password * In **Create + Online** mode, you must set: * DisplayName * **Room and Equipment mailboxes in Exchange Online require the `create` behavior.** With `enable` the connector stops with an error, because online there is no existing account for it to attach a mailbox to. **Mandatory parameters for creating a cloud user (Exchange Online ADD operation):** * UserPrincipalName * DisplayName * Password (can be left blank, but OpenIAM will not track it) {% hint style="info" %} **A new Exchange Online mailbox is not usable straight away.** Microsoft can take up to 24 hours to finish provisioning it, and until it does, mailbox settings cannot be applied. So on Exchange Online the connector creates the mailbox and stops there, rather than failing on settings the mailbox cannot accept yet. It reports success and lists the settings it left unapplied — `ArchiveQuota`, `ActiveSyncEnabled`, `SMTPDataJson`, distribution groups, `EmailAddressPolicyEnabled`, `PrimarySmtpAddress` and `EmailAddresses` — in a warning returned with the response. **A later save for the same identity applies them.** {% endhint %} ### User provisioning **Principal**: `UserPrincipalName` | Parameter | Description | Required | Values | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------- | | ConnectorModeSettings |

JSON defining connector scope and user behavior.

Scope:
- premise (default)
- online

User behavior:
- enable (default)
- create

Example: {"connectorScope":"premise","newUserBehavior":"create"}

| No | JSON | | UserPrincipalName | Logon name in UPN format (`username@domain`). Required only in on-premises Exchange and not needed in Enable mode. | Yes (Principal) | String | | Name | Unique mailbox name (max 64 chars). | Yes (Premise + Create) | String | | Password | Required for **Create + Premise** mode. Sets the AD user password. Not required for linked, resource, or shared mailboxes. | No | String | | MailboxType |

Defines mailbox type during creation (ignored for existing mailboxes).
Values: Room, Equipment, Shared.

| No | String | | Alias | Exchange alias (mail nickname). One value only. | No | String | | OrganizationalUnit |

Used only in Premise + Create mode to specify AD location.
Example: exchangeserver.com/Users

| No | String | | ActiveSyncMailboxPolicy | Used only in **Premise + Create** mode. Defines mobile device mailbox policy. Defaults to the system policy if not set. | No | String | | AddressBookPolicy | On-premises only. Specifies an address book policy by Name, DN, or GUID. | No | String | | ArbitrationMailbox | On-premises only. Defines arbitration mailbox for moderation. Accepts Name, DisplayName, Alias, DN, UPN, etc. | No | String | | IsArchive | If `True`, creates an archive mailbox. A value that is not recognizably a boolean is refused rather than guessed, because guessing wrong disconnects the archive. | No | Boolean | | ArchiveDatabase | On-premises only. Defines archive mailbox database. | No | String | | Database | On-premises only. Defines mailbox database. | No | String | | DisplayName | Display name for the mailbox. Required in Online mode. | Yes (Online) | String | | FirstName | Used only in **Create** mode for new users. | No | String | | ImmutableId | Used for GALSync and SAML federation scenarios. Must match AD FS settings if federation is used. | No | String | | Initials | Used only in **Premise + Create** mode. Max 6 chars. | No | String | | LastName | Used only in **Premise + Create** mode. | No | String | | ManagedFolderMailboxPolicy | Exchange 2010 only. Assigns managed folder policy. | No | String | | ManagedFolderMailboxPolicyAllowed | Exchange 2010 only. Bypasses MRM warnings for older Outlook clients. | No | Boolean | | ModeratedBy | Defines one or more moderators for message approval. Accepts Name, Alias, DN, GUID, etc. | No | String | | PrimarySmtpAddress | On-premises only. Defines primary email. Disables EmailAddressPolicyEnabled when set. | No | String | | ResetPasswordOnNextLogon | Used only in **Premise + Create** mode. Requires password reset at next logon. Default: false. | No | Boolean | | RetentionPolicy | On-premises only. Defines mailbox retention policy. Defaults to **Default MRM Policy**. | No | String | | RoleAssignmentPolicy | Defines role assignment policy. Defaults differ for Online vs. On-premises. | No | String | | SamAccountName | On-premises only. Pre-Windows 2000 logon name (max 20 chars). | No | String | | SendModerationNotifications | Defines moderation notification behavior: Always (default), Internal, Never. | No | String | | SharingPolicy | On-premises only. Defines sharing policy. Defaults to **Default Sharing Policy**. | No | String | | ThrottlingPolicy | On-premises only. Defines throttling policy. Defaults to none. | No | String | | AccountDisabled | On-premises only. Creates mailbox with disabled account. | No | Boolean | ### Connector-specific attributes Every attribute in the table above is an Exchange cmdlet parameter. The connector matches what OpenIAM sends against the parameters of the cmdlet it is about to run — `New-Mailbox`, `Enable-Mailbox` or `Set-Mailbox` — so a parameter of one of those cmdlets can be sent even when it is not listed above. The attributes below are the connector's own. They are not Exchange cmdlet parameters, and the connector acts on each one itself. | Attribute | Description | Operations | Scope | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------ | | `ArchiveQuota` | Storage quota for the archive mailbox. | ADD, MODIFY | `premise` only — the connector reports an error on `online` and `hybrid` | | `ActiveSyncEnabled` | Enables or disables Exchange ActiveSync for the mailbox. A value that is not recognizably a boolean is refused rather than guessed. | ADD, MODIFY | All | | `TimeZone` | Time zone for a **Room** or **Equipment** mailbox. Ignored for other mailbox types. | ADD | All | | `SMTPDataJson` | The mailbox's SMTP addresses, as one JSON value. See below. | ADD, MODIFY | All | | `DomainController` | Names the domain controller the connector writes to, instead of letting Exchange choose one. | ADD, MODIFY | All | | `EmailAddressPolicyEnabled` | Whether the Exchange email address policy applies to the mailbox. A value that is not recognizably a boolean is refused. | ADD, MODIFY | All | | `ProcessAddMailboxRights` | `True` makes the connector also run `Add-MailboxPermission` after it writes the mailbox, using whichever attributes in the same request match that cmdlet's parameters — `User` and `AccessRights`, for instance. `AccessRights` takes several values. | ADD, MODIFY | All | | `ProcessRemoveMailboxRights` | The same, for `Remove-MailboxPermission`. | MODIFY | All | | `SendAs` | Grants the named recipient **Send As** permission on the mailbox. | MODIFY | `online` only | | `RemoveSendAs` | Revokes **Send As** from the named recipient. | MODIFY | `online` only | **`SMTPDataJson`** carries a whole SMTP address change as a single value: {% code overflow="wrap" %} ```json { "ConnectorBehavior": "RelayOnOperation", "NoMailboxBehavior": "RaiseException", "PrimarySMTP": { "Operation": "set", "SMTPAddress": "john.doe@example.com" }, "SMTPData": [ { "Operation": "set", "SMTPAddress": "j.doe@example.com" }, { "Operation": "remove", "SMTPAddress": "jdoe@old.example.com" } ] } ``` {% endcode %} `ConnectorBehavior` decides what happens to the addresses the mailbox already has: * `RelayOnOperation` removes only the addresses listed with `"Operation": "remove"`. * `LeaveSetOnly` removes **every** secondary address the mailbox currently has, so it ends up with exactly the addresses listed with `"Operation": "set"`. The primary address is not touched. `NoMailboxBehavior` decides what happens when the mailbox cannot be read. `RaiseException` fails the request; any other value leaves the request successful, with a warning saying the addresses were not applied. ### Assigning a license A mailbox in Exchange Online needs a license that includes Exchange Online, but **the Exchange connector does not assign one**. Licensing is the Entra ID connector's job, and this connector dropped it in version 5.30.1.0 along with its MSOnline dependency. Assign the license through the Entra ID managed system, using its `LicensesToAssignJson` and `LicensesToRemoveJson` attributes. Both are documented, with their format, in [Entra ID/O365 connector](/connector-configuration/microsoft/5-azuread.md). {% hint style="warning" %} The Exchange connector still accepts `LicensesToAssignJson` and `LicensesToRemoveJson` without complaint, and does nothing with either. Setting them here assigns no license. {% endhint %} ## Reconciliation and synchronization How synchronization and reconciliation work in general is covered in the Administration guide — see [*Synchronize and import data*](/administration-guide/lifecycle/synchronize-and-import-data.md) and [*Configure reconciliation*](/administration-guide/lifecycle/configure-reconciliation.md). This section covers only what is specific to this connector. For synchronization, in addition to groovy transformation/validation scripts, set a search string in the ***SQL Query / Directory Filter*** field on the synchronization page (Webconsole → **Provisioning** → **Synchronization** → **Edit** your profile). This string defines what the connector queries from Exchange. Common examples: * `Get-Mailbox` – returns all user mailboxes with basic details (Name, Alias, ServerName, ProhibitSendQuota). * `Get-Mailbox | Select-Object` – returns all user mailboxes with full details. The connector runs this string as a PowerShell expression, and checks it first. It has to be **one pipeline that only reads**: * One statement — no `;` separators, no `param`/`begin`/`process` clauses, no conditions, loops, assignments or function definitions. * A reading verb. Anything that changes state is refused, so `Get-` and `Select-Object` are fine while `Set-`, `New-`, `Remove-`, `Export-` and `Invoke-` are not. For Exchange, `Search-Mailbox` and `Export-Mailbox` are refused by name. A query that fails the check stops the synchronization with a message saying which rule it broke. Shape the data in a transformation script rather than in the query. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/connector-configuration/microsoft/6-exchange.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.