Exchange connector

General information

Exchange connector gives you ability to manage Exchange mailboxes - create, modify, remove, lock, unlock using OpenIAM. This connector supports Exchange Server 2010 and upper.

Requirements

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

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 Managed System configuration inside 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 Exchange mailboxes.

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

Connecting to your directory

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

Exchange managed system configuration

Define attribute provisioning rules

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

Exchange PowerShell connector supports working with following identities:

  • Users mailboxes
  • Resource mailboxes
  • Distribution Groups

Connector mode setting

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 Exchange ability either to pick existing user from Active Directory and attach mailbox to existing user, or create new AD user and attach 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 user successfully you should ensure that you also set following attributes:

  • Name
  • Password

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

  • DisplayName
  • UsageLocation (2 letter value, for example, US)

If you work in ‘Create’ AND ‘Online’ (in cloud) scope, connector will create a cloud user for you and will assign a license that activates Exchange Online feature (setting proper license 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 2-nd provisioning request if you would need to set any additional mailbox parameters. That would also mean that you might see error message from connector side during the first provisioning (because Exchange mailbox would not be deployed yet). Those factors need to be taken into account when you work in ‘Create’ mode in cloud.

Mandatory parameters for creating 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 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 Exchange connector will create a user in AD and create a linked mailbox. If it is running in enable mode – linked mailbox will be created for existing user (if user does not exist – exception will be thrown);

Connector scope setting works with parameters:

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

New user behavior setting works with parameters:

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

Example:

{"connectorScope":"premise","newUserBehavior":"create"}
FalseJSON
UserPrincipalNameThis parameter is available only in 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 an 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 connector is working in ‘Create’ + ‘Premise’ mode. This will set 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 will be created user mailbox. 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 on-premises 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 on-premises 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 On-premise Exchange.
Could be specified for user creation. If ‘True’ archive mailbox will be created. Otherwise parameter will be ignored.
NoTrue or not specified
ArchiveDatabaseThis parameter is only available for 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 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 or functional only in Exchange Server 2010. The ManagedFolderMailboxPolicy parameter specifies the managed folder mailbox policy to enable for the mailbox that you create.NoString
ManagedFolder MailboxPolicy AllowedThis parameter is available or functional 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 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 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 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 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 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 applying | No | True if applied |

Assigning a license

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

LicensesToAssignJson parameter is mandatory from the perspective that we will need to assign Exchange online license. As Microsoft offers multiple possible packages where Exchange online is present, and assuming that we should name 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 E3 license with disabled SWAY and FLOW_O365_P2 and PowerBI license with disabled BI_AZURE_P0.

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

If you currently have one set of disabled plans and you need to enable them, but disable other 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 connector will stop executing after the user was created in Office365 and the license was assigned – because for freshly created user no mailbox settings can be applied, as well as some time is needed for the newly created user to get Exchange mailbox setup. If required, connector may throw an exception – according to what is required.

Synchronization

Working with reconcilation and synchronization is describeed in a separate document. In addition to specifying appropriate groovy scripts for transformation/validation rules, you should also set search string that should be set at 'SQL Query / Directory Filter' parameter of your sycnhroniztion page (Webconsole -> Top menu 'Provisioning' -> Synchronization -> Edit your synchronization profile). That string is actual request that will be executed by 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 connector usage: PowerShell connector usage. Troubleshooting steps are the same for all connectors of this type. Following information is sprcific 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 distribution group that exists in AD. The name of the group is being specified using DN that is valid. The cause is that Exchange cannot see this group. You should go to Exchange management area and check if this group is present. It appears that if the distribution group was created using Exchange – Get-DistributionGroupMember command - it is working, but the same command gives error if run against distribution group that was created directly in the AD.