Exchange Connector (.NET)

Last modified 22 Apr 2021 18:14 +02:00

Legacy connector for Microsoft Exchange servers based on .NET framework.

Functionalitystable
Development statusabandoned (no longer developed or maintained, legacy code)
Support statusunsupported
OriginICF
Support provided by
Target systemsMicrosoft Exchange servers
ProtocolPowerShell + ADSI
Source code

Connector usable for connecting to Active Directory and Microsoft Exchange. This is quite heavyweight connector and it works only in .NET connector server.

Exchange connector provides a superset of functionality of the Active Directory connector.

OBSOLETE and UNSUPPORTED

This connector is based on the .NET code developed by Sun Microsystems in 2000s. It is in fact just a special case of (now deprecated) .NET-based Active Directory Connector. This connector is OBSOLETE. It is likely that it will still work, but it is no longer developed, it is not maintained and it is not supported.

Please use dedicated SSH or Poweshell connectors instead.

Capabilities and Features

Provisioning YES

Live Synchronization

?

Password

YES

Activation

YES

Script execution

YES

History

This is mostly the original Sun ICF AD connector. Some extensions and fixes were done by ForgeRock and Evolveum.

Version Origin Binary Sources Build Date Description

1.4.1.20283

Version built by Evolveum

ZIP

github (Evolveum/openicf, branch master)

Oct 22nd, 2014

Experimental. Support for paged searches (VLV) for AD-fetched objects (users, orgs, groups).

1.4.1.20257

Version built by Evolveum

ZIP

github

Sep 9th, 2014

A lot of new functionality (many object classes, flexible scripting and schema processing). Seems to be quite stable. Recommended.

1.4.0.20165

Version built by Evolveum

ZIP

github

May 31st, 2014

Use this one in case of problems with 1.4.1.20257.

1.0.0.20108

Version built and partially tested by Evolveum

ZIP

Mar 2014

OBSOLETE. Use only with pre-3.0 versions of midPoint.

Documentation

Introduction

Exchange connector is able to provision Active Directory users, optionally with some Exchange-related artefacts. Specifically, currently supported kinds of users (recipient types in Microsoft terms) are shown in the following table. The first column contains Microsoft name for the recipient type, while the second one contains the respective value that should be put into RecipientType attribute (see below) to create specified kind of user.

Recipient type RecipientType attribute value Meaning

User mailbox

UserMailbox

Active Directory user with a mailbox in local Exchange organization.

Mail user

MailUser

Active Directory user that has a mailbox outside the Exchange organization. Each mail user has an external email address. Messages sent to this user are forwarded to the external email address.

User

User

Ordinary Active Directory user without any Exchange-related information.

Support for provisioning other types of recipients (e.g. distribution groups) is planned for the future.

Permissions

To successfully manage accounts with Exchange access, the administrative user should be put into the "Organizational Management" group (located in "OU=Microsoft Exchange Security Groups, …​").

Also it seems that at least for Microsoft Exchange 2013 the Connector Server should be running as the same administrative user, not LOCAL\_SYSTEM.

Comparison with Active Directory connector

Exchange connector is a superset of Active Directory connector. It is able to provision "pure" Active Directory users. However, there are two differences:

  1. Exchange connector requires Exchange installation to work, even if you do not plan to deal with any Exchange-specific objects.

  2. Exchange connector does not support UpdateAttributeValuesOp API interface, so adding and deleting attribute values (for both general AD attributes as well as Exchange-specific ones) is a bit less efficient in comparison with Active Directory connector, because these operations have to be emulated by Connector Server via GET-UPDATE operations pair. Direct replacing attribute values (UpdateOp API interface) is supported by both connectors.

Therefore, if you plan to use AD objects only, use AD connector. If you plan to use Exchange objects as well, use Exchange connector.

Aspect Active Directory connector Exchange connector

Required software

Windows Server

Windows Server with Exchange server (TODO: specify exactly which components of Exchange are needed)

Works with AD-only objects and attributes

YES

YES

Works with Exchange-specific objects and attributes

NO

YES

Supports efficient "attribute add/delete value" operation

YES

NO

Status

Production quality

Near-production quality (still in development)

Please note that the distribution ZIP file for Exchange connector contains both connectors (two DLL’s with supporting files), so when installing into Connector Server directory, it is sufficient to install this one file. On connector discovery, midPoint will show two connectors: Active Directory and Exchange. It is up to you whether you use AD or Exchange connector for working with any given resource.

Supported attributes

The connector supports all attributes supported by AD connector, along with the following Exchange ones. Descriptions are taken from Microsoft’s site.

Attribute Description AD counterpart Notes

RecipientType

Specifies the kind of user (see table above).

msExchRecipientDisplayType, msExchRecipientTypeDetails

Beware that when changing the value from UserMailbox to any other one, the user’s mailbox is deleted. Also when changing any value to User, all Exchange-related information from Active Directory user object are removed. When fetching data from the resource, two AD attributes are used to determine RecipientType: msExchRecipientDisplayType and msExchRecipientTypeDetails (see here). It is possible that in some cases, the mapping will be inaccurate. Please contact Evolveum support in such situations. For diagnostic purposes, values of these two attributes are provided (as read-only items) among account attributes fetched from the resource.

ExternalEmailAddress

External email address to which all messages for a MailUser should be forwarded.

targetAddress

This parameter is obligatory when creating a MailUser.These addresses are used without "smtp:" prefix - pure "user@domain" form is needed.

EmailAddresses (multivalued)

All addresses under which this user is known.

proxyAddresses

In contrary to other email addresses used by this connector, this parameter uses SMTP:/smtp: prefixes for individual address. "SMTP:" prefix is used for specifying primary SMTP address, "smtp:" for non-primary ones. Only one address can be designated as primary.It is not allowed to specify this attribute along with PrimarySmtpAddress attribute.Usually, these addresses are computed by default, unless EmailAddressPolicyEnabled is set to false.

EmailAddressPolicyEnabled

Are EmailAddresses updated automatically based on e-mail address policy?

msExchPoliciesExcluded

PrimarySmtpAddress

Primary SMTP address.

mail

Do not set/modify along with EmailAddresses.

Alias

The part of address before "@" sign.

mailNickname

The alias can be a combination of characters separated by a period with no intervening spaces. Don’t use special characters in the alias.

HiddenFromAddressListsEnabled

Specifies whether this mailbox is hidden from other address lists.

msExchHideFromAddressLists

Database

Specifies the database that contains the mailbox object. You can use either GUID or database name.

homeMDB

If not specified, default database is used. This attribute is not updatable. Any attempt to update it will fail. Mailboxes have to be moved explicitly using Exchange tools or dedicated PowerShell commands.

ForwardingSmtpAddress

Specifies a SMTP address where mail should be forwarded.

msExchGenericForwardingAddress

For detailed explanation, see e.g. this document.

DeliverToMailboxAndForward

If set to TRUE, messages are delivered to the mailbox and to the forwarding address. If set to FALSE, messages are delivered only to the forwarding address.

deliverAndRedirect

CustomAttribute1..15

Used to store any custom (additional) information.

extensionAttribute1..15

Connector configuration

Connector configuration is the same as for Active Directory connector, with one attribute added: ExchangeUri. It shoud contain a URI pointing to place where to execute PowerShell commands used to manage Exchange accounts. An example: http://exchange.example.com/PowerShell/. As the host name, DO NOT use "localhost", because in that case the Kerberos authentication to that host will fail.

A sample configuration:

   <connectorConfiguration>
      <icfc:resultsHandlerConfiguration xmlns:icfc="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/connector-schema-2">
         <icfc:enableNormalizingResultsHandler>true</icfc:enableNormalizingResultsHandler>
         <icfc:enableFilteredResultsHandler>false</icfc:enableFilteredResultsHandler>
      </icfc:resultsHandlerConfiguration>
      <icfc:configurationProperties xmlns:icfc="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/connector-schema-2"
                                    xmlns:ex="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/Exchange.Connector/Org.IdentityConnectors.Exchange.ExchangeConnector">
         <ex:ObjectClass>User</ex:ObjectClass>
         <ex:DirectoryAdminName>...</ex:DirectoryAdminName>
         <ex:DirectoryAdminPassword>...</ex:DirectoryAdminPassword>
         <ex:ExchangeUri>http://exserv1.abc.com/PowerShell/</ex:ExchangeUri>
         <ex:SyncDomainController>localhost</ex:SyncDomainController>
         <ex:CreateHomeDirectory>true</ex:CreateHomeDirectory>
         <ex:LDAPHostName>localhost</ex:LDAPHostName>
         <ex:SearchChildDomains>false</ex:SearchChildDomains>
         <ex:SyncGlobalCatalogServer>localhost</ex:SyncGlobalCatalogServer>
         <ex:Container>OU=TestOU,DC=abc,DC=com</ex:Container>
         <ex:DomainName>abc.com</ex:DomainName>
      </icfc:configurationProperties>
   </connectorConfiguration>

Some recommendations

  1. When creating mailboxes, the only attribute that is necessary to set, is RecipientType. Set it to UserMailbox and all other settings will be done via Exchange.
    For example, default addressing policies will be applied, and primary user mail address will be provided in PrimarySmtpAddress attribute (from where you can get it into midPoint via appropriate inbound mapping). Similarly, all addresses wil lbe present in EmailAddresses attribute.

  2. When creating external mail recipients, only two attributes to be set are RecipientType (set to MailUser) and ExternalEmailAddress.

  3. It is recommended to play for a while with the accounts on Resources→List resources→Accounts page and see how effect has changing RecipientType and setting some attributes on AD/Exchange user records.

  4. To prevent the execution of malicious scripts, PowerShell enforces an execution policy. By default, the execution policy is set to Restricted, which means that PowerShell scripts will not run. If a script execution error occurs when you set RecipientType field in the connector configuration, set the executon policy to RemoteSigned in Powershell using the command below,`Set-ExecutionPolicy RemoteSigned`Source: http://security.stackexchange.com/questions/1801/how-is-powershells-remotesigned-execution-policy-different-from-allsigned (thanks to Arda for providing this recommendation).

Resource Examples