GALSync: How to Extend GALSync to Provision Target Objects in Sub OUs Using a Configuration File

Introduction

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

The walkthrough contains documents on GALSync:

• 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)

Both are used as base to implement the GAL Sync.

 

Default Configuration

For this Wiki 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 below.

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

 

Hub-and-spoke

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 (OU)

│├ Domain2 (OU)

│└ Domain3 (OU)

├ ...

 

domain2.local (DOMAIN2)

├ ...

├┬ GAL Contacts (OU)

│├ Domain1 (OU)

│└ Domain3 (OU)

├ ...

domain3.local (DOMAIN3)

├ ...

├┬ GAL Contacts (OU)

│├ Domain1 (OU)

│└ Domain2 (OU)

├ ...

 

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 instead of rebuilding (default) data flows from scratch.

 

Security

Reference: MIIS/ILM 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 allow MIIS/ILM/FIMSync to 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 configuration

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_*
  • contact_gal_domain
  •  contact_gal_domain2
  • contact_gal_domain3
  • .

Attribute flow precedence

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

 

Management Agent 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 to adres list filter attribute

To allow Exchange admins creating an address list in AD, a certain 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

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 extensions 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 extensions
• 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. It's not really suitable for containing custom information (like the sub OU configuration.)

For that reason, 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 is 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= GALContacts,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 name="GAL Domain3">
 
   <contact-type>contact_gal_Domain3</contact-type>
 
   <target-ou>OU=Contacts,DC=domain3,DC=local</target-ou>
 
   <target-subou>OU=Domain3</target-subou>
 
  </galma>
 
 </galsync-mas>
 
</rules-extension-properties> 

Attribute flows

Per management agent, per managed object, all object flows that use (almost) only import attribute flows must be extended, to support the target-subou attribute import 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 to add
 
Case "targetSubOU"
 
Dim tempMAConfig As new GALMA
 
tempMAConfig = FindMA(csentry)
 
mventry(FlowRuleName).Value = tempMAConfig.targetSubOU
 
'# Customized Code to add
 
Case "TargetAddressMapping"

Metaverse extension (GALMV.vb)

To support subcontainers , change the provisioning code:

'# Customized Code to add
 
Dim strTargetDN As String  = _
 
mventry("targetSubOU").StringValue & "," & MAConfig.SynchronizationOU
 
'# Customized Code to add
 
'# Customized Code to change
 
Dim dn As ReferenceValue = _
 
'MA.EscapeDNComponent(rdn).Concat(MAConfig.SynchronizationOU)
 
MA.EscapeDNComponent(rdn).Concat(strTargetDN)
 
'# Customized Code to change

 

GAL Utils extension (GALUtil.vb)

GAL MA Class

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

Public Class  GALMA
 
'# Customized Code to add - begin 1
 
Public targetSubOU As String
 
'# Customized Code to add - end 1
 
End Class

XML Configuration tags

Add the customized code like:

Const GAL_SYNC_MA_XF_DELEGATION As String  = _
 
"cross-forest-delegation"
 
'# Customized Code to add - begin 2
 
Const GAL_SYNC_MA_TARGET_SUBOU As String  = _
 
"target-subOU"
 
'# Customized Code to add - end 2

FindMA Function

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

'# Customized Code to change - begin 3
 
'Private Function FindMA( _
 
Protected Function  FindMA( _
 
ByVal csentry As CSEntry) _
 
As GALMA
 
'# Customized Code to change - end 3

GetSubOUNames (Custom function, added to out-of-the box code)

'# Customized code to add - 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 to add - end 4

GetConFigurationData

/../
 
doc.Load(Utils.ExtensionsDirectory ├ "\GALSync.xml")
 
'# Customized code to add - 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 to add ) end 5
 
nodeMAs = doc.SelectSingleNode("/" & MMS_RULES_EXTENSION & "/" ├ GAL_SYNC_MAS)
 
/../
 
/../
 
MAConfig.MailRouting = False
 
'# Customized code to add - begin 6
 
MAConfig.targetSubOU = Nothing
 
'# Customized code to add - 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 to add - 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 to add - end 7
 
' Read contact type
 
/../

Exchange Server Configuration

With Exchange 2003/2007, it is not possible to create an global address list based on objects in an OU.

To create a global address list with a custom query, you must use an existing attribute of an user, contact, distribution group.

This procedure uses 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

 

 

See Also

• Global Address List Synchronization (GALSync)
• GALSync: How to Provision Contacts to Specific OU Units Based Upon an Originating Forest

 

References

• MIIS 2003 Walkthrough Scenarios