ILM Quick solution: Extending the GALSync to provision target objects in sub OUs

(draft)

The GALSync setup is fully documented in the MIIS 2003 Walkthrough Scenarios.

Both documents on GAL are used as base to implement the GAL Sync.

  • MIIS 2003: Global Address List (GAL) Synchronization (MIIS_2003_GAL_Synchronization.doc)
  • MIIS 2003 Walkthrough: Global Address List Synchronization (MIIS_2003_GAL_synchronization_Step_by_step.doc)

For this document the MIIS agent configuration is kept as default as possible.

Full detail on default configuration can be found in MIIS_2003_GAL_Synchronization.doc.

Only the differences, changes made to the default setup, will be recorded in the procedure.

The default GALSync configuration allows to provision target objects into one single container/OU.

In lots of cases customers wish to synchronize the existing address books within the different domains, targeting one central “Global Address Book”, presenting the different domains as subdivisions.

Customers want to have an overview via Outlook of all existing mail addresses, grouped by domain or entity.

And frequently they need to use a structured target container, provisioning target objects in sub OUs of the main target container.

The functionality to use sub OU’s in the target container must be added as customization into the IIFP/ILM server configuration.

Sample domain and OU structure

domain1.local (DOMAIN1)

+ …

+– GAL Contacts

¦ +– Domain2

¦ +– Domain3

+ …

domain2.local (DOMAIN2)

+ …

+– GAL Contacts

¦ +– Domain1

¦ +– Domain3

+ …

domain3.local (DOMAIN3)

+ …

+– GAL Contacts

¦ +– Domain1

¦ +– Domain2

+ …

GALSync Attributes

In the first stage of setup, the list of attributes that are configured by default (by default GALSync setup/wizard), will be maintained.

This will allow for a better review of the initial setup.

It’s much easier to remove the unwanted data flow configuration then rebuilding (default) data flows.

Security

Reference: MIIS Management Agent Communication Ports, Rights, and Permissions

Keep in mind you need a management agent connection account with the proper rights and permissions to read and write data in the targets.

(import, update, provisioning, …)

To allow the AD MA connection account to create, delete and update objects in the GAL contacts OU, the necessary permissions must be added to the GAL Contacts OU and its subfolders (using heritance).

By preference the administrator must create the container structure before you start provisioning.

You could create the subOUs during provisioning, but that is not part of the scope of this document.

Attribute flows

To detect the source of an object (linked to the target subcontainer) an attribute is added to the MV object definition (all objects): targetSubOU.

Details will be documented further in this document.

Metaverse configuation

Automated object creation by GALSync

When using the GALSync MA’s, MIIS automatically adds the necessary attribute flows to the new and to the existing management agents.

Also the MV is extended with new object types (like contact_XXX, where XXX is the name of the management agent, spaces replaces by underscore).

Add the targetSubOU attribute to the MV Objects

If you add another GALSync MA, you need to check that all active objects in the MV (MV objects in use by the GALSync) have the targetSubOU string attribute added.
This attribute is used to define the original source of an object, which also defines in which OU the related contact object must be created.

Check these MV object definitions:

    – person

    – group

    – contact_gal_*

      o contact_gal_domain1

      o contact_gal_domain2

      o contact_gal_domain3

      o …

Attribute flow precedence

Attribute flow precedence is handled automatically by the MIIS configuration wizard.

Management Agent Configuration

Most changes are not MA specific but applied to all MA’s as most MA’s use equal configuration.

Auto generation of attribute flows

When using the GALSync MA’s, MIIS automatically adds the necessary attribute flows to the new and to the existing management agents.

Also the MV is extended with new object types (like contact_XXX, where XXX is the name of the management agent, spaces replaces by underscore).

Add the targetSubOU attribute to the new GAL object

When you add a new management agent, the wizard automatically creates a new object type in the MV.
This object must include the new targetSubOU attribute. This attribute already exists in the attribute list but the attribute must be linked to the freshly created object.

Add targetSubOU attribute in attribute IMPORT flows

When implementing GAL Sync, the MA wizard automatically creates the needed attribute flows for the objects in the GAL Sync solution.

To determine the target in which a contact must be created, you need to add an additional attribute flow in the GAL Sync MA configuration.

Only for the (auto-created) attribute flows that mainly exist of import flows, you must add the “targetSubOU”.

The attribute flows that exist of export attribute flows must not contain the targetSubOU attribute.

Attribute flows that mainly exist of export attribute flows must not have this import flow added.

Below you’ll find some examples of flows that must be added:

Data Source Attribute Metaverse Attribute Type Flow Nulls
Object Type: Contact Object Type:contact_gal_<own MA>*
<dn> -> targetSubOU Rules Extension – targetSubOU
Object Type: user Object Type:person
<dn> -> targetSubOU Rules Extension – targetSubOU
Object Type: group Object Type:group
<dn> -> targetSubOU Rules Extension – targetSubOU

Add EXPORT attribute flow for extensionAttribute15

To allow for creating an address list in AD, the an attribute must be filled with the msExchOriginatingForest attribute.

In this procedure I chose “extensionAttribute15” for ease of use.

Export Attribute Flow
Data Source Attribute To Metaverse Attribute Mapping Type Allow Nulls
contact contact_gal_domain1
extensionAttribute15 <– msExchOriginatingForest Direct Allow
contact person
extensionAttribute15 <– msExchOriginatingForest Direct Allow
contact group
extensionAttribute15 <– msExchOriginatingForest Direct Allow

Consider to disable EXPORT attribute flow for native source objects

If you do NOT wish to update the native source objects (like user objects) or do not have the permission to do so, you should disable the export on attributes for SOURCE objects. (read-only for source objects).

In the following attribute flows, remove the update export attribute flow of the native source objects.

IMPORTANT:

In a multiple server and multiple company routing scenarios there might be routing issues with the contacts which do not have the X500 address created on the user and contact. You might have internal routing between servers generating NDR’s while the email is attempted to be routed to a mail gateway.

You recognize these flows as one single export attribute flow to the proxyAddresses attribute between a list of import attribute flows.

Data Source Attribute* Metaverse Attribute* Type*
Object Type:

user

Object Type:

person

proxyAddresses ß legacyExchangeDN Rules Extension – ProxyAddressesMappingBackwards
Object Type:

contact

Object Type:

contact_<own MA name>

proxyAddresses ß legacyExchangeDN Rules Extension – ProxyAddressesMappingBackwards
Object Type:

group

Object Type:

group

proxyAddresses ß legacyExchangeDN Rules Extension – ProxyAddressesMappingBackwards
Object Type:

msExchangeDynamicDistributionList

Object Type:

group

proxyAddresses ß legacyExchangeDN Rules Extension – ProxyAddressesMappingBackwards

* : to apply if applicable

Remove obsolete export attribute flows

Attributes that are not of interest should be removed from the export attribute flows.

(Leave the import attribute flows intact!)

targetSubOU attribute flow definition

GALMA.vb must be extended with an additional flowrule in MapAttributesForImport.

Source code – enable provisioning in sub containers

As mentioned before ((Ref. MIIS_2003_GAL_Synchronization.doc)

“When synchronizing with a connected data source that uses a hierarchical structure such as Active Directory, Microsoft Identity Integration Server 2003 does not export container operations. That is, when provisioning a child object, Microsoft Identity Integration Server 2003 does not create the parent automatically. The management of containers with hierarchies must be done completely in the connected data source.”

The functionality to use sub OU’s in the target container will be added as customization into the MIIS server configuration.

The GALSync code extension are gathered into 1 project solution.

The source code of the GALSync setup is installed by default in the MIIS program files directory (%program files%\Microsoft Identity Integration Server\SourceCode\GalSync).

The solution exists of 3 base code files

    – GALMA.vb : the GAL management agent extensions

    – GALMV.vb : the GAL metaverse extentions

    – GALUtil.vb: code library for functions used in GALMA.vb and GALMV.vb

In addition the solution uses a XML file (GALSync.XML) to read MA l configuration options.

 

Galsync.xml

IMPORTANT:

The galsync.xml file in the Extensions folder is automatically updated/managed by the system, when the MA’s in MIIS are added, updated or changed.

GALSync.xml is very volatile.

For that reason, it’s not really suitable for containing custom information (like the sub OU configuration.

Another, similar xml file is created to contain custom information: GALSync_subOUs.xml.

GALSync_subOUs.xml

For each management agent, a section (<target-subou>) has to be added to the MA configuration, to support the provisioning in subcontainers.

This information is quite stable and are administrator-managed.

At the moment of configuration this information must be updated to the real life configuration data (AD Container info).

<rules-extension-properties>

<galsync-mas>

<galma name="GAL Domain1">

<contact-type>contact_gal_Domain1</contact-type>

<target-ou>OU=GAL Contacts,DC=domain1,DC=local</target-ou>

<target-subou>OU=Domain1/target-subou>

</galma>

<galma name="GAL Domain2">

<contact-type>contact_gal_Domain2</contact-type>

<target-ou>OU=Contacts,DC=domain2,DC=local</target-ou>

<target-subou>OU=Domain2</target-subou>

</galma>

</galma>

</galsync-mas>

</rules-extension-properties>

Attribute flows

Per management agent, per managed object, all object flows that (almost) only use incoming attribute flows (imports) must be extended, to support the target-subou attribute flow.

Object attribute flows that are (mainly) export must not be extended for the moment.

Management agent extension (GALMA.vb)

Advanced Import flow for targetSubOU

To support the advanced import attribute flow, the GALMA code must be extended.

The following code (between the ‘#Customized Code markers) has been added in the “Public Sub MapAttributesForImport” section:

/../

Select Case FlowRuleName

‘# Customized Code

Case “targetSubOU”

Dim tempMAConfig As new GALMA

tempMAConfig = FindMA(csentry)

mventry(FlowRuleName).Value = tempMAConfig.targetSubOU

‘# Customized Code

Case “TargetAddressMapping”

/../

Metaverse extension (GALMV.vb)

To support subcontainers , change the provisioning code:

/../

‘# Customized Code

Dim strDN As String = _

mventry(“targetSubOU”).StringValue & “,” & MAConfig.SynchronizationOU

Dim dn As ReferenceValue = _

MA.EscapeDNComponent(rdn).Concat(strTargetDN)

‘MA.EscapeDNComponent(rdn).Concat(MAConfig.SynchronizationOU)

‘# Customized Code

/../

Remark:

Microsoft Identity Integration Server 2003 does not create the parent automatically.

The hierarchical structure is not dynamic, each MA has it’s fixed position in the target GAL contacts OU.

So the function to create the parent is not added to the procedure.

GAL Utils extension (GALUtil.vb)

GAL MA Class

In the GALUtil.vb code, the following sections must be updated:

/../

Public Class GALMA

Public MAName As String

Public SynchronizationOU As String

Public MailDomainNames() As String

Public ContactOUs() As String

Public ContactType As String

Public AdminGroup As String

Public MailRouting As Boolean

Public XFDelegation As Boolean

‘# Customized Code begin 1

Public targetSubOU As String

‘# Customized Code end 1

End Class

/../

XML Configuration tags

Add:

Const GAL_SYNC_MA_XF_DELEGATION As String = _

“cross-forest-delegation”

‘# Customized Code begin 2

Const GAL_SYNC_MA_TARGET_SUBOU As String = _

“target-subOU”

‘# Customized Code end 2

FindMA Function

To call the FindMA function outside the code section, “private” cannot be used.

‘# Customized Code begin 3

‘Private Function FindMA( _

Protected Function FindMA( _

ByVal csentry As CSEntry) _

As GALMA

‘# Customized Code end 3

GetSubOUNames (Custom, added)

‘# Customized code begin 4

Public Sub GetSubOUNames(ByRef refHT As Hashtable)

Dim xMLDoc As XmlDocument = New XmlDocument

xMLDoc.Load(Utils.ExtensionsDirectory + "\GALSync_subOUs.xml")

Dim xmlnodeMA As XmlNode

Dim iCount As Integer

Dim xMLMaAttribute As XmlAttribute

Dim strMAName As String

Dim xMLnode As XmlNode

Dim xMLNodeMAs As XmlNode = _

xMLDoc.SelectSingleNode( _

    "/" & MMS_RULES_EXTENSION & "/" + GAL_SYNC_MAS)

Dim xMLnodeMAList As XmlNodeList = _

xMLNodeMAs.SelectNodes(GAL_SYNC_MA)

For iCount = 0 To xMLnodeMAList.Count – 1

xmlnodeMA = xMLnodeMAList.Item(iCount)

‘ Find MA Name

For Each xMLMaAttribute In xmlnodeMA.Attributes

    If "name" = xMLMaAttribute.Name() Then

      strMAName = xMLMaAttribute.InnerText().Trim()

    Exit For

    End If

Next

If IsNothing(strMAName) Then

    Throw New UnexpectedDataException( _

    "No MA name Attribute in subOU configuration XML")

End If

‘ Read target Sub OU info

XmlNode = xmlnodeMA.SelectSingleNode(GAL_SYNC_MA_TARGET_SUBOU)

If Not IsNothing(XmlNode) Then

    ‘add MA Name and MA subOU name to hashtable

    ‘refHT.add(MAName, SubOUName)

    refHT.Add(strMAName, xMLnode.InnerText().Trim())

End If

Next iCount

End Sub

‘# Customized code end 4

GetConFigurationData

/../

doc.Load(Utils.ExtensionsDirectory + "\GALSync.xml")

‘# Customized code begin 5

” GALSync.xml is updated/modified by ILM/MIIS when saving a GAL MA configuration

” thus GALSync.XML is not usable to store custom data, like subOU info

” the subOU info is stored in a separate XML file "GALSync_subous.xml", similar to GALSync.XML

” GALSync_subous.xml info is loaded in to hash table

Dim hTsubOU As New Hashtable

GetSubOUNames(hTsubOU)

‘# Customized code end 5

nodeMAs = doc.SelectSingleNode("/" & MMS_RULES_EXTENSION & "/" + GAL_SYNC_MAS)

/../

/../

MAConfig.MailRouting = False

‘# Customized code begin 6

MAConfig.targetSubOU = Nothing

‘# Customized code end 6

‘ Find MA Name

For Each maAttribute In nodeMA.Attributes

If “name” = maAttribute.Name() Then

MAConfig.MAName = maAttribute.InnerText().Trim()

Exit For

End If

Next

If IsNothing(MAConfig.MAName) Then

Throw New UnexpectedDataException( _

“No MA name Attribute in configuration XML”)

End If

‘# Customized code begin 7

” Read target Sub OU info from hash table

” that was initialized before

”if HT does not contain the MAName, throw error

If Not hTsubOU.Contains(MAConfig.MAName) Then

Throw New UnexpectedDataException( _

"No MA name Attribute in hash table configuration")

End If

MAConfig.targetSubOU = hTsubOU.Item(MAConfig.MAName).ToString

‘# Customized code end 7

‘ Read contact type

/../

Exchange Server Configuration

As far as I know, and experienced, It is not possible to create an global address list based on a OU.

To create a global address list with a custom query, you must use an existing attribute of an user, contact, distribution group.
Therefore I decided to use the extensionAttribute15, to store a value.

The msExchOriginatingForest attribute, which is maintained by the GAL Sync, is propagated to the extensionAttribute15 attribute.

This allows for creating an address list based on a contact attribute.

Every target forest has a corresponding OU container in the GAL contacts structure.
For every existing (or new) target forest, create an address list.

ExtensionAttribute15 contains the FQDN of the source forest.

Example: domain1.local for GAL Domain1, domain2.local for GAL DOmain2

IMPORTANT:

This article is not handling provisioning to Exchange 2007 / Exchange 2010.

When using GALSync with these systems, make sure you install the proper tooling. (Powershell, Exchange Management Console)

Also check ILM 2007 FP1 SP1.

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s