Exchange connector

General information

The Exchange connector provides the ability to manage (create, modify, remove, lock, unlock) Exchange mailboxes using OpenIAM. This connector supports Exchange Server 2010 and later.

Requirements

To run this connector, the Exchange server should be accessible from the machine running the connector and it should be possible to establish a PowerShell session to the Exchange instance. Other requirements are common for all .NET/PowerShell connectors and are described in the "PowerShell connector usage" document.

Exchange connector requires .Net Framework 4.7.2

For working with Exchange Online, Exchange connector reqiures MSOnline module and Exchange Online PowerShell V2 module. Please make sure they are installed.

Installation and connection to OpenIAM

All PowerShell connectors are installed in the same way, which is described in the document: PowerShell connector installation

General usage

All PowerShell connectors are used in the same way, which is described in the document: PowerShell connector usage

Service account information:

During the Managed System configuration inside the OpenIAM /webconsole section you should set Login ID, which will be used as a service account for OpenIAM. Exchange uses service accounts of AD to perform operations on the Exchange mailboxes.

Please note that the service account should be set to include your domain name. For example, 'openiamtest\serviceAccount'

Connecting to your directory

To connect OpenIAM to the Exchange service using the connector you need to specify the service account on the Managed System configuration page. This service account should have sufficient privileges to perform actions that you would like using the PowerShell connector.

Exchange managed system configuration

Define attribute provisioning rules

The Exchange connector can work with both on premise and Exchange online modes. By default, the connector operates in ‘On premises’ mode. To change it to work with Exchange online, OpenIAM should send the ConnectorModeSettings attribute. This adds flexibility, so if an organization moves from Exchange on premises to cloud, the connector remains unchanged with the exception of features that might be specific to one of those environments.

Exchange PowerShell connector supports working with the following identities:

  • Users mailboxes
  • Resource mailboxes
  • Distribution Groups

Connector mode setting

The ConnectorModeSettings attribute defines default connector behavior. It controls 2 parameters:

  • Connector scope (Premise or Online)
  • Default user creation behavior (Create or Enable)

Connector scope was described above, and user creation behavior refers to the Exchange ability to either pick an existing user from Active Directory and attach a mailbox to an existing user, or create a new AD user and attach a mailbox to a newly created user.

This parameter should be sent as JSON string looking like:

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

If this attribute is not specified, Connector scope is treated as “premise” and new user behavior as “enable”.

Important to note

If you work in ‘Create’ AND ‘Premise’ scope, to be able to create a user successfully you should ensure that you also set the following attributes:

  • Name
  • Password

If you work in ‘Create’ AND ‘Online’ (in cloud) scope, to be able to create a user successfully you should ensure that you also set the following attributes:

  • DisplayName
  • UsageLocation (2 letter value. For example, US).

If you work in ‘Create’ AND ‘Online’ (in cloud) scope, the connector will create a cloud user for you and will assign a license that activates Exchange Online features (how to set proper licenses will be described later in this document). However, according to information from Microsoft, provisioning a new mailbox does not happen immediately and may take up to 24 hours. That means that you need to take into account that you may need to run a second provisioning request if you would need to set any additional mailbox parameters. That would also mean that you might see error messages from the connector during the first provisioning (because the Exchange mailbox would not be deployed yet). Those factors need to be taken into account when you work in the ‘Create’ mode in the cloud.

Mandatory parameters for creating a cloud user (required for ADD operation for Exchange online):

  • UserPrincipalName
  • DisplayName
  • Password (can be left blank, but OpenIAM would not be aware about this in this case)
  • UsageLocation (needs for setting license for some plans)

User provisioning

Principal - UserPrincipalName

ParameterDescriptionRequiredValues
ConnectorModeSettingsThere are several pre-defined settings that that determine how the Exchange connector will be operating. Those settings consist of:

Connector scope settings – determine which target system type is used: Exchange on-premise, Exchange online;

New user behavior settings – in some cases Exchange can create or enable mail user. For user creation the Exchange connector will create a user in AD and create a linked mailbox. If it is running in enable mode – a linked mailbox will be created for the existing user (if user does not exist – exception will be thrown);

Connector scope setting works with these parameters:

Exchange on premise (connectorScope = premise). The default setting.
Exchange online (connectorScope = online)

The New user behavior setting works with these parameters:

EnableUser (newUserBehavior = enable).
The default setting.
CreateUser (newUserBehavior = create)

Example:

{"connectorScope":"premise","newUserBehavior":"create"}
FalseJSON
UserPrincipalNameThis parameter is available only in the on-premises Exchange. Also, it is not required if we work in ‘Enable’ mode. The UserPrincipalName parameter specifies the logon name for the user account. The UPN uses the email address format username@domain. Typically, the domain value is the domain where the user account resides.Yes (Principal)String (UPN format)
NameThe Name parameter specifies the unique name of the mailbox. The maximum length is 64 characters.Yes (On Premise and Create mode)String
PasswordThis parameter is used if the connector is working in ‘Create’ + ‘Premise’ mode. This will set the password for a newly created user in Active Directory. The Password parameter specifies the password for the mailbox (the user account that's associated with the mailbox). This parameter isn't required if you're creating a linked mailbox, resource mailbox, or shared mailbox, because the associated user accounts are disabled for these types of mailboxes.NoString
MailboxTypeIs used during mailbox creation. For existing mailbox operations is ignored. Create resource mailbox. If this parameter is not set, then the mailbox will be created. Mailbox types:

Room – Room mailbox
Equipment – Equipment mailbox
Shared – Shared mailbox
NoString
AliasThe Alias parameter specifies the Exchange alias (also known as the mail nickname) for the recipient. This value identifies the recipient as a mail-enabled object and shouldn't be confused with multiple email addresses for the same recipient (also known as proxy addresses). A recipient can have only one Alias value.NoString
OrganizationalUnitIs used only during ‘Premise’ + ‘Create’ connector mode. Ignored for other modes. The OrganizationalUnit parameter specifies the location in Active Directory where the new mailbox is created.

Example: exchangeserver.com/Users
NoString
ActiveSyncMailboxPolicyIs used only on ‘Premise’ mode during user creation. Ignored for other operations. The ActiveSyncMailboxPolicy parameter specifies the mobile device mailbox policy that's applied to the mailbox. You can use any value that uniquely identifies the policy. For example:

Name
Distinguished name (DN)
GUID

If you don't use this parameter, the default mobile device mailbox policy is used.
NoString
AddressBookPolicyThis parameter is available only in the on-premise Exchange. The AddressBookPolicy parameter specifies the address book policy that's applied to the mailbox. You can use any value that uniquely identifies the address book policy.For example:

Name
Distinguished name (DN)
GUID
NoString
ArbitrationMailboxThis parameter is available only in the on-premise Exchange.

The ArbitrationMailbox parameter specifies the arbitration mailbox that's used to manage the moderation process for this recipient. You can use any value that uniquely identifies the arbitration mailbox.

For example:


Name
Display name
Alias
Distinguished name (DN)
Canonical DN
domain name\account name
Email address
GUID
LegacyExchangeDN
SamAccountName
User ID or user principal name (UPN)
NoString
IsArchiveThis parameter is only available for the on-premise Exchange.
Could be specified for user creation. If ‘True’ archive mailbox will be created. Otherwise the parameter will be ignored.
NoTrue or not specified
ArchiveDatabaseThis parameter is only available for the on-premise Exchange.
The ArchiveDatabase parameter specifies the Exchange database that contains the archive that's associated with this mailbox. You can use any value that uniquely identifies the database.

For example:

Name
Distinguished name (DN)
GUID
NoString
DatabaseThis parameter is only available for the on-premise Exchange. The Database parameter specifies the mailbox database that contains the mailbox. You can use any value that uniquely identifies the database.

For example:

Name
Distinguished name (DN)
GUID
NoString
DisplayNameThe DisplayName parameter specifies the display name of the mailbox. The display name is visible in the Exchange admin center, in address lists, and in Outlook. The maximum length is 256 characters.Yes, if working in Online modeString
FirstNameIs used only if connector is in ‘Create’ mode and is performing new user creation. Ignored for other operations.
The FirstName parameter specifies the user's first name.
NoString
ImmutableIdThe ImmutableId parameter is used by GAL synchronization (GALSync) and specifies a unique and immutable identifier in the form of an SMTP address for an Exchange mailbox used for federated delegation when requesting Security Assertion Markup Language (SAML) tokens. If federation is configured for this mailbox and you don't set this parameter when you create the mailbox, Exchange creates the value for the immutable ID based upon the mailbox's ExchangeGUID and the federated account namespace, for example, 7a78e7c8-620e-4d85-99d3-c90d90f29699@mail.contoso.com.

You need to set the ImmutableId parameter if Active Directory Federation Services (AD FS) is deployed to allow single sign-on into an off-premises mailbox and AD FS is configured to use a different attribute than ExchangeGUID for sign-on token requests. Both, Exchange and AD FS must request the same token for the same user to ensure proper functionality for a cross-premises Exchange deployment scenario.
NoString
InitialsIs used only if connector works in ‘Premise’ + ‘Create’ mode during user creation. Ignored for other operations. The Initials parameter specifies the user's middle initials. Should not be more than 6 characters.NoString
LastNameIs used only if connector works in ‘Premise’ + ‘Create’ mode during user creation. Ignored for other operations. The LastName parameter specifies the user's last name.NoString
ManagedFolder MailboxPolicyThis parameter is available only in Exchange Server 2010. The ManagedFolderMailboxPolicy parameter specifies the managed folder mailbox policy to enable the mailbox that you create.NoString
ManagedFolder MailboxPolicy AllowedThis parameter is available only in Exchange Server 2010. The ManagedFolderMailboxPolicyAllowed parameter specifies whether to bypass the warning that messaging records management (MRM) features aren't supported for clients using versions of Microsoft Outlook earlier than Office Outlook 2007. When a managed folder mailbox policy is assigned to a mailbox using the ManagedFolderMailboxPolicy parameter, the warning appears by default unless the ManagedFolderMailboxPolicyAllowed parameter is used. Outlook 2003 Service Pack 3 clients are supported but are provided limited functionality for MRM.NoString
ModeratedByThe ModeratedBy parameter specifies one or more moderators for this recipient. A moderator approves messages sent to the recipient before the messages are delivered. A moderator must be a mailbox, mail user, or mail contact in your organization. You can use any value that uniquely identifies the moderator.

For example:

Name
Display name
Alias
Distinguished name (DN)
Canonical DN
Email address
GUID

You need to use this parameter to specify at least one moderator when you set the ModerationEnabledparameter to the value true.
NoString
PrimarySmtpAddressThis parameter is only available in the on premise Exchange. The PrimarySmtpAddress parameter specifies the primary return email address that's used for the recipient. If it's available on this cmdlet, you can't use the EmailAddresses and PrimarySmtpAddress parameters in the same command. If you use the PrimarySmtpAddress parameter to specify the primary email address, the command sets the EmailAddressPolicyEnabled property of the mailbox to False, which means the email addresses of the mailbox aren't automatically updated by email address policies.NoString
ResetPassword OnNextLogonIs used only if connector works in ‘Premise’ + ‘Create’ mode during user creation. Ignored for other operations. The ResetPasswordOnNextLogon parameter specifies whether the user is required to change their password the next time they log on to their mailbox. Valid values are: true and false, which is default value.NoTrue, False
RetentionPolicyThis parameter is available only in on-premises Exchange for user creation process. The RetentionPolicy parameter specifies the retention policy that you want applied to this mailbox. You can use any value that uniquely identifies the policy. For example: Name; Distinguished Name (DN); GUID
Retention policies consist of tags that are applied to mailbox folders and mail items to determine the period of time that the items should be retained. If you don't use this parameter, the retention policy named Default MRM Policy is applied to the mailbox.
NoString
RoleAssignmentPolicyThe RoleAssignmentPolicy parameter specifies the role assignment policy that's applied to the mailbox. You can use any value that uniquely identifies the role assignment policy. For example: Name; DN; GUID
In Office 365, if you don't use this parameter, the default role assignment policy named Default Role Assignment Policy is automatically applied to the mailbox. In on-premises Exchange, no role assignment policy is automatically applied to the mailbox.
NoString
SamAccountNameThis parameter is available only in the on-premises Exchange. The SamAccountName parameter (also known as the pre-Windows 2000 user account or group name) specifies an object identifier that's compatible with older versions of Microsoft Windows client and server operating systems. Unicode characters are allowed, but accented characters may generate collisions (for example, o and ö match). The maximum length is 20 characters.NoString
SendModeration NotificationsCannot be assigned during ‘enabling’ mailbox, but could be used for modifying. The SendModerationNotifications parameter specifies when moderation notification messages are sent. Valid values are:

Always: Notify all senders when their messages aren't approved. This is the default value.
Internal: Notify senders in the organization when their messages aren't approved.
Never: Don't notify anyone when a message isn't approved.

This parameter is only meaningful when moderation is enabled (the ModerationEnabled parameter has the value true).
NoString
SharingPolicyThis parameter is available only in the on-premises Exchange. The SharingPolicy parameter specifies the sharing policy that's applied to the mailbox. You can use any value that uniquely identifies the sharing policy. For example: Name, DN, GUID

If you don't use this parameter, the sharing policy named Default Sharing Policy is applied to the mailbox.
NoString
ThrottlingPolicyThis parameter is available only in the on-premises Exchange. The ThrottlingPolicy parameter specifies the throttling policy that's applied to the mailbox. You can use any value that uniquely identifies the throttling policy. For example:

Name
Distinguished name (DN)
GUID

By default, no throttling policy is applied to the mailbox.
NoString
AccountDisabledThis parameter is available only in the on-premises Exchange. The AccountDisabled switch specifies that the user account associated with the mailbox is disabled. The mailbox is created, and the associated account is created, but the account is disabled so you can't log on to the mailbox. Should be true for applyingNoTrue if applied

Assigning a license

If you need to create a cloud user using the Exchange connector, it should create a user and assign a license to this user. In this case the user mailbox will be created automatically when the license package that contains Exchange Online is assigned.

The LicensesToAssignJson parameter is mandatory from the perspective that we will need to assign the Exchange online license. As Microsoft offers multiple possible packages where Exchange online is present and assuming that we should name the tenant cloud of the particular organization, this parameter needs to be specified.

Example:

[{"LicenseName":"openiamdemocloud:ENTERPRISEPACK","DisabledPlans":["SWAY","FLOW_O365_P2"]},{"LicenseName":"openiamdemocloud:POWER_BI_STANDARD","DisabledPlans":["BI_AZURE_P0"]}]

In this example, we are setting the E3 license with disabled SWAY and FLOW_O365_P2 and PowerBI license with disabled BI_AZURE_P0.

If you need to keep the whole package enabled, you should leave DisabledPlan like an empty array ([]).

If you currently have one set of disabled plans and you need to enable them, but have disabled another set of plans, you just set the final list that should be disabled to the DisabledPlans and all plans that belong to the package but not listed there will be enabled.

Please keep in mind, that by default the connector will stop executing after the user was created in Office365 and the license was assigned, because for a freshly created user no mailbox settings can be applied, as well as some time is needed for the newly created user to get an Exchange mailbox set up. If required, the connector may throw an exception.

Synchronization

Working with reconcilation and synchronization is describeed in a separate section. In addition to specifying appropriate groovy scripts for transformation/validation rules, you should also set a search string that should be set to the 'SQL Query / Directory Filter' parameter of your synchronization page (Webconsole -> Top menu 'Provisioning' -> Synchronization -> Edit your synchronization profile). That string is an actual request that will be executed by the connector to find/filter users (mailboxes) from Exchange.

Most typical queries are:

  • Get-Mailbox - selects all user mailboxes including basic information such as Name, Alias, ServerName, ProhibitSendQuota
  • Get-Mailbox | Select-Object * - selects all user mailboxes including all user data

Connector Troubleshooting and Tips

Connector troubleshooting is covered in the document that describes all .NET/PowerShell connectors usage: PowerShell connector usage. Troubleshooting steps are the same for all connectors of this type. The following information is specific for this connector.

ErrorDescription
The operation couldn't be performed because object 'x' couldn't be found on 'y’.This exception could be thrown while setting a distribution group that exists in AD. The name of the group is being specified using a DN that is valid. The cause is that Exchange cannot see this group. You should go to the Exchange management area and check if this group is present. It appears that if the distribution group was created using the Exchange/Get-DistributionGroupMember command, it is working, but the same command gives an error if run against a distribution group that was created directly in AD.