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.
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.
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
| Parameter | Description | Required | Values |
|---|---|---|---|
| ConnectorModeSettings | There 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"} | False | JSON |
| UserPrincipalName | This 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) |
| Name | The Name parameter specifies the unique name of the mailbox. The maximum length is 64 characters. | Yes (On Premise and Create mode) | String |
| Password | This 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. | No | String |
| MailboxType | Is 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 | No | String |
| Alias | The 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. | No | String |
| OrganizationalUnit | Is 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 | No | String |
| ActiveSyncMailboxPolicy | Is 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. | No | String |
| AddressBookPolicy | This 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 | No | String |
| ArbitrationMailbox | This 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) | No | String |
| IsArchive | This 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. | No | True or not specified |
| ArchiveDatabase | This 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 | No | String |
| Database | This 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 | No | String |
| DisplayName | The 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 mode | String |
| FirstName | Is 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. | No | String |
| ImmutableId | The 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. | No | String |
| Initials | Is 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. | No | String |
| LastName | Is 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. | No | String |
| ManagedFolder MailboxPolicy | This parameter is available only in Exchange Server 2010. The ManagedFolderMailboxPolicy parameter specifies the managed folder mailbox policy to enable the mailbox that you create. | No | String |
| ManagedFolder MailboxPolicy Allowed | This 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. | No | String |
| ModeratedBy | The 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. | No | String |
| PrimarySmtpAddress | This 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. | No | String |
| ResetPassword OnNextLogon | Is 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. | No | True, False |
| RetentionPolicy | This 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. | No | String |
| RoleAssignmentPolicy | The 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. | No | String |
| SamAccountName | This 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. | No | String |
| SendModeration Notifications | Cannot 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). | No | String |
| SharingPolicy | This 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. | No | String |
| ThrottlingPolicy | This 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. | No | String |
| AccountDisabled | This 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 applying | No | True 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.
| Error | Description |
|---|---|
| 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. |