The sticking problem is the objectClass. Typically objects in LDAP will have more than one objectClass, and the only way to set them in MIIS/ILM is in the metaverse extension code. It is no different with FIM. There is no way to set objectClass from a codeless sync rule, and you can’t set it in an export attribute flow. 

So a Metaverse extension is still the way to go. Here is an example of a provisioning rule for OpenLDAP. I am creating a posixAccount, mostly as a way of showing how to add the dependant objectClasses. Your objectClasses will no doubt vary.

I have included a couple of functions that I am using to generate a password hash and to find the next uidNumber. Note for the latter function the Terminate sub is also implicated.

Imports Microsoft.MetadirectoryServices
Imports System.DirectoryServices
Imports System.Text
Imports System.IO
Imports System.Security.Cryptography

Public Class MVExtensionObject
    Implements IMVSynchronization

    '' It is a better practise to put these constants in a lookup file
    Const OL_SERVER As String = "myldapserver.mydomain.com"
    Const OL_ROOT As String = "dc=myldap,dc=mydomain,dc=com"
    Const OL_OU_USERS As String = "ou=users,dc=myldap,dc=mydomain,dc=com"
    Const OL_UIDFILE As String = "C:\Program Files\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\openLDAP\uidNumber.txt"
    Const OL_READ_USER As String = "cn=fimread,ou=users,dc=myldap,dc=mydomain,dc=com"
    Const OL_READ_PW As String = "password"
    Const OL_DEFAULT_GROUP As String = "1000"

    Public Sub Initialize() Implements IMVSynchronization.Initialize
        ' TODO: Add initialization code here
    End Sub

    Public Sub Terminate() Implements IMVSynchronization.Terminate
    '' Deleting this file forces a new LDAP search the next time, allowing for accounts which may have been created manually.
        If File.Exists(OL_UIDFILE) Then
            File.Delete(OL_UIDFILE)
        End If
    End Sub

    Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision
        Select Case mventry.ObjectType
            Case "person"
                Provision_OpenLDAPPerson(mventry)
        End Select
    End Sub

    Sub Provision_OpenLDAPPerson(ByVal mventry As MVEntry)
        Dim ShouldExist As Boolean = False
        Dim DoesExist As Boolean
        Dim CSEntry As CSEntry
        Dim OLMA As ConnectedMA = mventry.ConnectedMAs("openLDAP")
        Dim expectedDN As ReferenceValue
        Dim Container As String

        '' Should the account exist? (Add more logic here to decide)
        ShouldExist = True

        '' Does the account already exist?
        If OLMA.Connectors.Count = 0 Then
            DoesExist = False
        Else
            DoesExist = True
        End If

        '' Generate the expected DN for the user - to use in creating or moving
        If mventry("accountName").IsPresent And ShouldExist Then
            Dim RDN As String = "cn=" & mventry("accountName").StringValue.ToLower
            expectedDN = OLMA.EscapeDNComponent(RDN).Concat(OL_OU_USERS)
        End If

        '' Take action based on values of ShouldExist and DoesExist
        If ShouldExist And DoesExist Then
            '' Check if rename needed
            If csentry.DN.ToString.ToLower <> expectedDN.ToString.ToLower Then
                csentry.DN = expectedDN
            End If

        ElseIf ShouldExist And Not DoesExist Then
            '' Create Account

            ' Set objectClasses
            Dim oc As ValueCollection
            oc = Utils.ValueCollection("inetOrgPerson")
            oc.Add("person")
            oc.Add("organizationalPerson")
            oc.Add("inetOrgPerson")
            oc.Add("posixAccount")
            oc.Add("shadowAccount")
            oc.Add("simpleSecurityObject")
            CSEntry = OLMA.Connectors.StartNewConnector("posixAccount", oc)
            CSEntry.DN = expectedDN

            ' Find next available uidNumber
            CSEntry("uidNumber").Value = = NextUidNumber(OL_SERVER, OL_ROOT).ToString

            ' Set initial password
            CSEntry("userPassword").Value = "{MD5}" & GenerateHash("INitial001")

            ' The following could also be done as export flow rules
            CSEntry("gidNumber").Value = OL_DEFAULT_GROUP
            CSEntry("sn").Value = mventry("lastName").Value
            CSEntry("givenName").Value = mventry("firstName").Value
            CSEntry("cn").Value = mventry("accountName").Value.ToLower
            CSEntry("uid").Value = mventry("accountName").Value.ToLower
            CSEntry("displayName").Value = mventry("firstName").StringValue & " " & mventry("lastName").StringValue.ToUpper

            CSEntry.CommitNewConnector()

        ElseIf Not ShouldExist And DoesExist Then
            '' Delete
            CSEntry = OLMA.Connectors.ByIndex(0)
            CSEntry.Deprovision()

        End If
    End Sub

    Public Function NextUidNumber(ByVal ldapServerName As String, ByVal searchRoot As String) As Integer
    '' The first time the function runs it finds the highest uidNumber in LDAP and stores it in a text file.
    '' On subsequent runs it retrieves the last uidNumber straight from the text file. This allows for sync runs
    '' where multiple accounts are created.
    '' The text file is deleted as part of the Terminate routine.

        Dim oSearcher As New DirectorySearcher
        Dim oResults As SearchResultCollection
        Dim oResult As SearchResult
        Dim lastuid As Integer = 0

        If File.Exists(UIDFILE) Then
            Dim fileReader As New StreamReader(UIDFILE)
            lastuid = CInt(fileReader.ReadLine)
            fileReader.Close()
        Else
            Try
                With oSearcher
                    .SearchRoot = New DirectoryEntry("LDAP://" & ldapServerName & "/" & searchRoot, _
                                                     "cn=root,dc=ldap,dc=eesp,dc=ch", "hesso_2010", AuthenticationTypes.FastBind)
                    .PropertiesToLoad.Add("uidNumber")
                    .Filter = "uidNumber=*"
                    oResults = .FindAll()
                End With

                For Each oResult In oResults
                    If oResult.GetDirectoryEntry().Properties("uidNumber").Value > lastuid Then
                        lastuid = oResult.GetDirectoryEntry().Properties("uidNumber").Value
                    End If
                Next

            Catch e As Exception
                Throw New UnexpectedDataException(e.Message)
                Return -1
            End Try
        End If

        Dim fileWriter As New StreamWriter(UIDFILE, False)
        fileWriter.WriteLine(lastuid + 1)
        fileWriter.Close()

        Return lastuid + 1
    End Function

    Private Function GenerateHash(ByVal SourceText As String) As String
        ' Returns the MD5 hash of the SourceText string.
        Dim Ue As New UTF7Encoding()
        Dim ByteSourceText() As Byte = Ue.GetBytes(SourceText)
        Dim Md5 As New MD5CryptoServiceProvider()
        Dim ByteHash() As Byte = Md5.ComputeHash(ByteSourceText)
        Return Convert.ToBase64String(ByteHash)
    End Function

End Class

The background to this is a BPOS (Microsoft cloud services) project I’ve been working on. BPOS doesn’t actually give you any way to disable an account while keeping the mailbox, so I wanted to be able to reset a BPOS password as part of the deprovisioning cycle. I also wanted to do this quickly and efficiently. BPOS gives you two methods to change a password: through the admin console and through powershell. Obviously powershell is the way to go for automation. 

At the same time I was thinking of other times where I may want to fire off a powershell cmdlet – such as when initailly activating the account, when adding BPOS services, changing a mailbox quota or when adding mailbox trustees. With this method I think I have found a nicely generalised solution. My XMA will run any powershell cmdlet and all I need to do is provision these “command” objects, based on changes in the metaverse. 

Warning

You can run into problems with this approach where FIM Sync unprovisions the unexported command object because it thinks you don’t need it any more. I found this when I tied the provisioning of the BPOS command object to the moving of an AD account, but then exported the AD MA first. The Sync service thought the command was then not needed and removed. An extra status flag should sort this out.

FIM Portal Workflow may be better

The other comment is that this is a Sync Service based way of approaching this problem. A better bet, if you’re using the FIM Portal, is probably to fire the powershell cmdlets directly from the Portal as part of a workflow. Unfortunately, at the moment, this means a custom workflow, which I haven’t really gotten my head around yet.

Delta Imports Only

I have designed this XMA to only ever do Delta Imports. This is because I only actually care about the commands that were just run – and also, it makes the code a lot easier to write.

If at some point I decide I need to be able to do a Full Import of all commands I’ve ever run, I think I will have to involve a SQL table.

Steps

Preparing the XMA

The server prerequisites are covered in this post. You should also review this other post about creating a remote powershell XMA. The big difference with this MA is that it is Call-based, giving me the ExportEntry Sub which runs against each individual export.

I still need a CSV file to feed to the MA creation wizard for its schema. My CSV, very simply, contains the following:

     cmdlet,arguments,date,time,identity,status

The “identity” here is an identifier for the BPOS object that I’m going to run the command against, and is not actually a unique identifier for the command itself. Because I don’t have a single unique attribute I use the following combination as the anchor: cmdlet + identity + date.

This has the useful side-effect of ensuring only one command object for a particular activity will be configured per day – though if the export of the command were to repeatedly fail you would find a new command object being provisioned the next day. Just something to watch out for.

Retry Mechanism

I also configure one direct Export Attribute Flow:      Constant “success” –> status

This is my feedback mechanism. I force the export of “success” to my command object – but if the running of the command actually failed I write “failed” into the delta import file – so this actually makes a re-export happen. Until the Sync service can export and then re-import a status of “success” it will keep trying.

CS Extension

Here’s the CSExtension. Because this is for BPOS I’ve added the appropriate PSSnapin in the BeginExport sub. You may not need to add any snapins. Or you may just need the standard Exchange ones in which case it looks like you don’t need to add a snapin at all, because you have a nice Exchange-specific shell URI to use. There are plenty of other posts about that so I won’t say more.  
  

Imports Microsoft.MetadirectoryServices
Imports System.Management.Automation
Imports System.Management.Automation.Host
Imports System.Management.Automation.Runspaces
Imports System.IO

Public Class MACallExport
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleCallExport

    Const SHELL_URI As String = "http://schemas.microsoft.com/powershell/Microsoft.Powershell"
    Const MA_FOLDER As String = "C:\Program Files\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\BPOS commands\"
    Const DELTA_FILE As String = "delta.csv"
    Const HEADER As String = "cmdlet,arguments,date,time,identity,status"

    Dim myRunSpace As Runspace
    Dim bposCred As PSCredential

    Dim fileDelta As StreamWriter

    Public Sub GenerateImportFile(ByVal filename As String, ByVal connectTo As String, ByVal user As String, ByVal password As String, ByVal configParameters As ConfigParameterCollection, ByVal fullImport As Boolean, ByVal types As TypeDescriptionCollection, ByRef customData As String) Implements IMAExtensibleFileImport.GenerateImportFile
        ' TODO: Remove this throw statement if you implement this method
        Throw New EntryPointNotImplementedException
    End Sub

    Public Sub BeginExport(ByVal connectTo As String, ByVal user As String, ByVal password As String, ByVal configParameters As ConfigParameterCollection, ByVal types As TypeDescriptionCollection) Implements IMAExtensibleCallExport.BeginExport
        ' Start new DELTA file.
        fileDelta = New StreamWriter(MA_FOLDER & DELTA_FILE, False, System.Text.Encoding.Default)
        fileDelta.WriteLine(HEADER)
        fileDelta.Close()

        ' Create credential for attaching to remote server
        Dim remotepass As New Security.SecureString
        Dim c As Char
        For Each c In password
            remotepass.AppendChar(c)
        Next
        Dim remoteCred As New PSCredential(user, remotepass)

        ' Create credential for attaching to BPOS
        ' The configParameters are configured on the Additional Parameters page of the MA.
        Dim bpospass As New Security.SecureString
        For Each c In configParameters("bposPassword").Value
            bpospass.AppendChar(c)
        Next
        bposCred = New PSCredential(configParameters("bposUser").Value, bpospass)

        ' Open remote powershell session
        Dim serverUri As New Uri("http://" & connectTo & ":5985/wsman")
        Dim connectionInfo As New WSManConnectionInfo(serverUri, SHELL_URI, remotecred)
        myRunSpace = RunspaceFactory.CreateRunspace(connectionInfo)
        Dim psException As PSSnapInException = Nothing
        myRunSpace.Open()

        Dim psh As PowerShell = PowerShell.Create()
        psh.Runspace = myRunSpace
        psh.AddCommand("Add-PSSnapin")
        psh.AddParameter("Name", "Microsoft.Exchange.Transporter")
        psh.Invoke()

    End Sub

    Public Sub ExportEntry(ByVal modificationType As ModificationType, ByVal changedAttributes As String(), ByVal csentry As CSEntry) Implements IMAExtensibleCallExport.ExportEntry
        Dim psh As PowerShell = PowerShell.Create()
        Dim psresult As New System.Collections.ObjectModel.Collection(Of PSObject)
        psh.Runspace = myRunSpace

        psh.AddCommand(csentry("cmdlet").StringValue)

        Dim arguments As String = csentry("arguments").StringValue
        Dim parameter As String
        For Each parameter In arguments.Split("-".ToCharArray)
            If parameter.Contains(" ") Then
                If parameter.Contains("$true") Then
                    psh.AddParameter(parameter.Split(" ".ToCharArray, 2)(0), True)
                ElseIf parameter.Contains("$false") Then
                    psh.AddParameter(parameter.Split(" ".ToCharArray, 2)(0), False)
                Else
                    psh.AddParameter(parameter.Split(" ".ToCharArray, 2)(0), parameter.Split(" ".ToCharArray, 2)(1))
                End If
            End If
        Next
        psh.AddParameter("Credential", bposCred)
        psresult = psh.Invoke()

        Dim strLine As String = csentry("cmdlet").StringValue & "," & csentry("arguments").StringValue & "," _
                                & csentry("date").StringValue & "," & csentry("time").StringValue & "," & csentry("identity").StringValue
        fileDelta = New StreamWriter(MA_FOLDER & DELTA_FILE, True, System.Text.Encoding.Default)

        If psh.Streams.Warning.Count > 0 Then
            fileDelta.WriteLine(strLine & ",warning: " & psh.Streams.Warning.Item(0).Message)
        ElseIf psh.Streams.Error.Count > 0 Then
            fileDelta.WriteLine(strLine & ",error: " & psh.Streams.Error.Item(0).ErrorDetails.Message)
        Else
            fileDelta.WriteLine(strLine & ",success")
        End If
        fileDelta.Close()

        psh.Dispose()
    End Sub

    Public Sub EndExport() Implements IMAExtensibleCallExport.EndExport

        myRunSpace.Close()

    End Sub

End Class

Provisioning Code

Here’s an example of provisioning a command object from the MVExtension code.

' To change BPOS password, provision a BPOS command object
Dim bposCmd As CSEntry
bposCmd = mventry.ConnectedMAs(MAName_BPOScmd).Connectors.StartNewConnector("command")
bposCmd("cmdlet").StringValue = "Set-MSOnlineUserPassword"
bposCmd("identity").StringValue = mventry("bposIdentity").StringValue
bposCmd("date").StringValue = Now.Date.ToString("d")
bposCmd("time").StringValue = Now.TimeOfDay.ToString
Dim randompassword As String = < your random password generator here >
bposCmd("arguments").StringValue = "-Identity " & mventry("bposIdentity").StringValue & " -Password " & randompassword & " -ChangePasswordOnNextLogon $false"
Try
     bposCmd.CommitNewConnector()
Catch ex As ObjectAlreadyExistsException
End Try

Phase One Joins and Data Matching

The tedious truth is that most IdM projects must begin with a phase of data matching and cleaning. Before you can start to automate management of identities, you need a predictable
data set around which to base your rules. Many organizations today, whether due to changes in IT personnel, company mergers, variable naming conventions or lack of guidance on handling resignations, have existing user account bases that can only be described as a mess.

This document covers some of the methods you can use with ILM to get through that first project phase. Unfortunately there are no magic bullets here – eye-straining, brain-numbing trawls through long lists of unmatched accounts cannot usually be avoided. What you can do is try to extract quality data, and construct your lists as helpfully as possible, so they can be targeted at the people whose eyeballs and brains are most likely to give the best response.

It must be added that this is a very big topic, and the methods you choose will depend on the data you are faced with, and the aims of your project.

Joins

Really, it’s all about joins.

Once existing accounts are joined to their correct data source (such as matching an HR record to an AD account) you can begin to flow updates.

Once you have a clear idea who does and does not have an account in a target directory, you can begin to make provisioning and deprovisioning decisions.

Your eventual aim is a simple Join Rule

When you first start data matching, you will use a lot of different join rules, and you will make joins manually and with CSV files (more on that below). But keep
this in mind: 

Any join made manually, or with extra effort, should be considered temporary. 

There are various situations in ILM which can only be reliably rectified by a clear-out and re-import of a connector space.

Always plan for this.

Ideally, when you re-import a connector space, you will have a single, direct join rule which effortlessly re-joins all your objects. And to achieve this we use… 

Breadcrumbing

Once the join is verified you should export a uniquely identifying attribute, such as an employee number, to the target directory.

After that a simple “employeeID = employeeID” type join rule is all you will need. 

Sometimes you are faced with an import-only system. For either technical or political reasons you are not able to export the breadcrumb attribute.

There are a couple of things you can do: 

1.  Import the DN or other identifying attribute from the target directory into an attribute on the Metaverse object.But be warned, you could still lose these joins if you had to repopulate your Metaverse.
2.  To be on the safe side you should also “save” these joins by exporting an identifying pair somewhere else – for example using a database or text file
   MA, as pictured below.

Understanding Join Rules

There are some key points to note about Join Rules: 

1. Join rules operate on the CS object. It takes one CS object and attempts to find a match among all Metaverse objects of the correct type, even if they are already joined.
2. Components within one rule are AND-ed together – they must all match.
3. Multiple rules are evaluated top down, so put your strongest rules at the top.
4. While you can offer variations on a CS objects attribute using an Advanced Join Rule, you have to find an exact match with an attribute already on a Metaverse
   object. There are no “StartsWith” or “Contains” comparisons.

Resolve Join

At the bottom of the Join Rule configuration you will see a check box “Use rules extension to resolve”.

Here you can link to code you write under the ResolveJoinSearch subroutine in the MA extension.

The Resolve rule is used when ILM finds multiple possible matches in the Metaverve (including already-joined objects).

All the possible matches into the collection rgmventry and your job, in the code, is to check through them, looking for the best possible match.

If your code finds an ideal match you return the index number of the object in imventry, and set the value of ResolveJoinSearch to true.

The following example only joins if a single, unjoined Metaverse object was found. 

Public Function ResolveJoinSearch(ByVal joinCriteriaName As String, ByVal csentry As CSEntry, ByVal rgmventry() As MVEntry, ByRef imventry As Integer, ByRef MVObjectType As String) As Boolean Implements IMASynchronization.ResolveJoinSearch
   Select Case joinCriteriaName
      Case "Resolve_NotYetJoined"
         If rgmventry.Length = 1 AndAlso _
            rgmventry(0).ConnectedMAs("AD").Connectors.Count = 0  Then
            imventry = 0
            Return True
         Else
            Return False
         End If
   End Select
End Function

Advanced Join Rules

A simple join rule directly matches a connector space attribute to a Metaverse attribute:

With an Advanced Join Rule you construct a list of possible values with which to find an exact match in the Metaverse:

Sometimes you can use code rules to make your list of possible matches (eg., presenting a phone number in different formats); other times you have to use long
look-up lists of possible variations (try genealogy websites for name-variation lists).

The following example uses a lookup file of aliases, where each line has the possible variations on a name.

If a match to the first name is found on the connector space object, the whole line is added to the possible values to search for in the Metaverse. 

Elizabeth,Liz,Beth,Betty
David,Dave,Davey
Jerome,Jérôme
… 

Public Class MAExtensionObject
   Implements IMASynchronization
   Dim fileAliases As System.IO.StreamReader
   Dim arrAliases As String()
   Dim i As Integer

   Public Sub Initialize() Implements IMASynchronization.Initialize
      fileAliases = New System.IO.StreamReader("C:\aliases.txt",  System.Text.Encoding.Default)
      i = 0
      While Not fileAliases.EndOfStream
         ReDim Preserve arrAliases(i)
         arrAliases(i) = fileAliases.ReadLine
         i = i + 1
      End While

     fileAliases.Close()
   End Sub

   Public Sub MapAttributesForJoin(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByRef values As ValueCollection) Implements IMASynchronization.MapAttributesForJoin
      Select FlowRuleName
         Case "Join_aliases"
            Dim aliasList As String
            Dim value As String

            For Each aliasList In arrAliases
               If aliasList.Contains(csentry("givenName").Value) Then
                  For Each value In aliasList.Split(",".ToCharArray)
                     values.Add(value)
                  Next
	      End If
            Next
         End Select
     End Sub
End Class

Using CSV Files

A lot of the difficult account matching will probably be done outside ILM.

It is therefore useful to be able to “export” lists of possible matches, and later, “import” the joins from a CSV file.

Be careful when writing to files from extension code – the DLL doesn’t unload for five minutes after the MA run completes, which means you may have to wait for it
to finish writing to the file. If you’re in a hurry, recompiling the code will force the DLL to finish writing to the file. 

Export Possible Matches to a CSV file

You can use the Resolve rule to export possible matches to a CSV file. The following example resolves the join rule “sn | Direct | lastname”. As a match on the last
name alone is too weak for an immediate join, we just write the possible matches to the text file. 

Public Class MAExtensionObject Implements IMASynchronization
   Dim fileMatches As System.IO.StreamWriter

   Public Sub Initialize() Implements IMASynchronization.Initialize
      fileMatches = New System.IO.StreamWriter("C:\possible matches.txt", System.Text.Encoding.Default)
   End Sub

   Public Sub Terminate() Implements IMASynchronization.Terminate
      fileMatches.Close()
   End Sub

   Public Function ResolveJoinSearch(ByVal joinCriteriaName As String, ByVal csentry As CSEntry, ByVal rgmventry() As MVEntry, ByRef imventry As Integer, ByRef MVObjectType As String) As Boolean Implements IMASynchronization.ResolveJoinSearch
      Select Case joinCriteriaName
         Case "Resolve_Lastname"
            Dim MAName As String = csentry.MA.Name
            Dim mvobject As MVEntry
            Dim cFirstname, mFirstname As String

            If csentry("givenName").IsPresent Then
               cFirstname = csentry("givenName").StringValue
            Else
               cFirstname = "UNKNOWN"
            End If

            If mvobject("firstname").IsPresent Then
               mFirstname = mvobject("firstname").StringValue
            Else
               mFirstname = "UNKNOWN"
            End If

            For Each mvobject In rgmventry
               If mvobject.ConnectedMAs(MAName).Connectors.Count = 0  Then
                  fileMatches.WriteLine(csentry("sn").StringValue & ";" _
     		   & cFirstname & ";" _
     		   & mvobject("lastname").StringValue & ";" _
     		   & mFirstname)
               End If
            Next
            Return False
         End Select
   End Function
End Class

You will need to adapt this code of course. Firstly, you probably want to export a lot more identifying information in your CSV file – department, email address,
dn … whatever helps. Next, it can really help to supplement your possible matches with a probability score. This is where you do a series of tests and add points-
the more points, the higher the chance of the match. For example: 

• Names similar*          +1
• Department the same +1
• City the same           
  +1

*Some tips for testing if names are similar: 

• Strip out all spaces, dashes and hyphens then compare;
• Check if one string is contained in the other (so that “Sally-Anne” gets
  a point for “Sally”);
• Use a function which compares string similarity (search “Soundex” and “Levenshtein
  distance”).

Join from CSV

You can use an Advanced Join Rule to “import” joins from a CSV file.

Firstly, our CSV file must be constructed like this: 

CS_identifier;MV_identifier 

For example, if we are trying to match an AD account against Metaverse objects imported from the HR system, we populate the CSV with the AD DN and the employeeID: 

CN=Fred Bloggs,OU=User,OU=MyOrg,DC=mydomain,DC=com;0012988 

Next we create the Advanced Join Rule which will look up the csobject’s DN in the text file, but use the employeeID to search the Metaverse. 

Note that you can’t actually use the DN in the join rule – but that’s ok, just use any attribute that definitely exists. Eg., 

sAMAccountName | Rules extension – Join_CSV | employeeID 

And now for the code : 

Imports Microsoft.MetadirectoryServices

Public Class MAExtensionObject Implements IMASynchronization
   Dim joins As String()
   Dim i As Integer

   Public Sub Initialize() Implements IMASynchronization.Initialize
      Dim fileJoins As System.IO.StreamReader
      Dim strLine As String
     'Open the csv file and read into an array
      fileJoins = New System.IO.StreamReader("C:\joins.csv", System.Text.Encoding.Default)
      i = 0
      While Not fileJoins.EndOfStream
         ReDim Preserve joins(i)
         joins(i) = fileJoins.ReadLine
         i = i + 1
      End While
      fileJoins.Close()
   End Sub

   Public Sub MapAttributesForJoin(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByRef values As ValueCollection) Implements IMASynchronization.MapAttributesForJoin
      Select FlowRuleName
         Case "Join_CSV"
            'If the csentry DN is found in the joins array, then
            'use the paired employeeID to search the Metaverse.
            For i = 0 To joins.Length - 1
               If joins(i).Contains(csentry.DN.ToString) Then
                  values.Add(joins(i).Split(";")(1))
               End If
         Next

   End Select
End Sub

Reporting

People will ask you questions like “How many people have you joined in system X but not in Y?”, “How sure are you that the joins are correct?”, “Which department
has the most unidentified accounts?” It’s best to be prepared for these sorts of questions. 

Querying the Metaverse

Once data is in the Metaverse it is a simple matter to access it for reporting, either by exporting it into a reporting table, or by directly querying the underlying
tables (as long as you’re careful to do it when ILM is idle, or else use NOLOCK). 

So consider this: During the data cleaning phase, import all identifying attributes into the Metaverse from all sources. 

For example: You’ve made a join between a user in AD and an HR record.

Under normal operations you would consider HR as the master source for the name, and you would only flow it from there.

You wouldn’t bother importing the name attributes from AD – in fact you’re more likely to be overwriting them with export flow rules.

However, during the data matching phase, you’re probably not ready to start overwriting attributes, and the information about current values can be very important in your
verification and reporting.

Now, if you have a look at the mms_metaverse table in the ILM database, you will see how simple it is to query the progress of your joins, and also to judge
on what criteria the joins were made.

Some example queries… 

/* HR person with no join to AD */

select HR_lastname, HR_firstname, HR_employeeid from mms_metaverse
where AD_dn is null 

 /* HR person with join to AD */

select HR_lastname, HR_firstname, HR_employeeid, AD_lastname,AD_firstname,AD_dn from mms_metaverse
where AD_dn is not null 

Caution
As mentioned above you need to be careful when directly querying the Metaverse tables.If your system is already in production, and you happen to be adding in a new data source, then you may be better off employing a SQL MA to export the data you’re interested in to another table, where you can query it as much as you like without risk of locking errors.

Querying the Connector Space

Unfortunately it is not so simple to query the connector space to, for example, report on that state of your disconnected objects.

It’s a great pity that you can’t just save results from the Joins page in the Identity Manager GUI, so your options are: 

SQL query – The CS table holds data differently to the Metaverse tables.

It is possible to query for disconnectors in this way, however you will only be able to retrieve the CN of objects – which may not be sufficient to identify them. 

select cs.rdn from dbo.mms_connectorspace cs
join dbo.mms_management_agent ma
on cs.ma_id = ma.ma_id
left outer join dbo.mms_csmv_link mv
on mv.cs_object_id = cs.object_id
where ma.ma_name = 'My MA'
and mv.mv_object_id is null
and cs.connector_state = 0

CSExport – The command-line utility csexport.exe, found in the <ILM program>\bin folder, will allow you to dump connector space objects to an XML file. 

Report directly from the data source – Once an object in the data source has been correctly identified you will ideally export a unique attribute out to it. It may then be possible to identify the non-joined objects as those which don’t possess this attribute. 

Project to a different object type – ILM processes joins before projections, so it is fairly simple to project all non-joined objects to a different Metaverse object type – for example, one called “disconnectors”. This may help in reporting on an overall status direct from the Metaverse tables.

Note however that to make these objects once again available for joins they will have to be disconnected from the MVExtension provisioning code. 

Advanced Tips and Tricks

Join to Multi-value Attribute

Sometimes you may need to join to a value in a multi-value attribute. An example is searching through all the proxyAddresses for a match against
a single email address. 

When the multi-valued attribute exists in the connector space, and the single valued attribute is in the Metaverse, this is very easily accomplished. Just use an Advanced Join Rule to break the multi-valued attribute down into the values list used by the join rule. 

 Public Sub MapAttributesForJoin(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByRef values As ValueCollection) Implements IMASynchronization.MapAttributesForJoin
   Select FlowRuleName
      Case "Join_proxyAddresses"
         Dim alias As String
         For Each alias In csentry("givenName").Values
            values.Add(alias)
         Next
   End Select
End Sub

However, when the multi-valued attribute has already been imported into the Metaverse you will have a problem. While you can join on a multi-valued attribute, you have to join on the whole thing. There is no way that you can match one value out of a multi-valued Metaverse attribute against a single-valued connector space attribute. 

Some possible options: 

• Import the multi-valued attribute into a series of single-valued attributes in the Metaverse, eg., proxy1, proxy2, proxy3 …
• Use a different Metaverse object type to do the project and join the other way around.

Multiple Possibilities in the Connector Space

All the joining techniques so far have been based around a single connector space object, with one or more possible matches in the Metaverse. But what do you do if you want to work the other way around, where there are multiple possible matches in the connector space for a single Metaverse object, and you want to pick the best one? Unfortunately this is not straight-forward. There is no way to offer a selection of connector space objects in a join rule, as joins always work on a single connector space object at a time. You can judge the merits of the current CS object, but you can’t tell if there’s a better one coming up. One way around this is to do everything with CSV files. 

1. Use the ResolveJoinSearch to write possible joins to a CSV, but don’t actually join anything,
2. Do your matching outside ILM, then
3. Use a CSV with an Advanced Join Rule to make the joins.

Too much data

If you have an enormous number of accounts, and different data sources to trawl through, you may be best off doing your data matching outside of ILM, and then just using the CSV join rule above to make the joins.  Check out the Fuzzy Lookup Transformation from the Enterprise version of SQL SSIS for help here. 

Take-Home Thoughts

• Complex join rules are a means to an end – not the end itself.
• Breadcrumbing is essential for automation.
• When matching on weak rules (eg., surname only) then verify the match another way.
• You can’t do it all in ILM. CSV, Excel and fuzzy lookup algorithms will also help, but an element of by-hand matching is inevitable.
• Get the matching and breadcrumbing sorted out before you start flowing and provisioning.This will make for a happier project, stake holders, users and YOU!

Extra Reading

• Design Concepts for Correlating Digital Identities
• Correcting incorrect joins

About the Author

Carol Wapshere is an ILM MVP and contributor of a few of these documents now. She has always believed that putting the work in up-front will save you lots of headaches in the long run. It’s a self-defense strategy really – there’s nothing worse than having to go over and over (and over) the same ground again and again, especially when you’d already moved on to something new and far more interesting. Keep it neat, and keep it simple, and things should work just fine. 

Thanks to Markus Vilcinskas and Paul Loonen for their help with this document.

Handy!

I just posted this article in the Greatest Hits series of the ILM Technet forum. It describes some of the methods and considerations around disabling and deleting users accounts with ILM.

In Identity Management, deprovisioning is every bit as important as provisioning – in fact the security guys would say it is more important.

End-of-life management may have been one of the determining factors that got the IdM project started in the first place – while most
organizations have a variety of scripts and processes they use to create accounts and assign permissions, the cleanup when a person leaves is often not handled so well.

General rules for object deletion have been already well covered in Markus’ article
Understanding Deletions in ILM; however there is more that can be said on the subject of user accounts, for which an immediate delete is often not appropriate.

This article shows how you can use ILM to configure a flexible deprovisioning solution that is customized to your technical, organizational and compliance needs.

Account Deprovisioning Scenarios in this document

We are going to look at the following types of account deprovisioning:

1. Simple deletion
2. Disabling the account
3. Deleting the account on a time-delayed basis
4. Stopping ILM from managing the account without actually deleting it (disconnection)

Parts to the Account Deprovisioning Puzzle

Depending on your needs, you will most likely have to piece together a number of different elements to achieve the desired result.

Account Disabling:

Deactivating an object normally involves changing one or more of its attributes (eg.: setting userAccountControl on an AD user), and the usual way to do this is with an export attribute flow (EAF).

See code example “Disabling Flow Rules” below.

Moving deactivated accounts:

• A common practice is to put disabled accounts in a particular place, such as a “Disabled” OU.For AD this is a “Rename” activity, and is typically done in the metaverse
  extension code.
• For the “Stop management” scenario it is also possible to move the account just prior to disconnecting it in the MA Extension Deprovision method.

See code example “Metaverse Deprovisioning” below.
 

Deleting the connector space (CS) object:

• The first step to deleting an account is to delete the object that represents it in the connector space.This can happen in one of the following two ways:
  • The joined Metaverse object is deleted
  • The joined Metaverse object was disconnected, either manually or by using the
    CSEntry.Deprovision() method in the
    metaverse extension code.
• In both cases a deletion will only happen if the “Configure Deprovisioning” tab on the MA configuration has been set as follows:
  • “Stage a delete on the object for the next export run”, or
  • “Determine with a rules extension” AND the rules extension code returns
    DeprovisionAction.Delete.

 
See code example “MA Deprovision Sub” below
 
See “Metaverse Deprovisioning” for an example of the CSEntry.Deprovision() method.
 

Deleting the account in the connected data source (CDS):

• To delete the actual object in the CDS, we must first delete the connector space object using the methods above, after which we should find an export of type “delete” ready in the connector space.It is then just a matter of running an Export.
  • Note that the account used by the MA must have permission to delete objects of this type in the CDS.
  • Note also that if the MA is of type “Extensible Connectivity” you must write a Delete method in the Connected Data Source extension (see example below).

 
See code example “XMA Delete Method” below.
 

Time dependant deletion:

• Sometimes you want to delete an object on a certain date – perhaps an expiration date, or 3 months after the account was disabled.To do this you need the date available on the Metaverse object, which means you have to flow it into the Metaverse from somewhere.
  • An example for AD accounts is to use a spare attribute on the account, such as info or one of the extensionAttributes, to write the date at the same time as you disable the account.Flow this value back into the Metaverse and the information will be available.

 
See code example “Metaverse Deprovisioning” below.
 

Deprovisioning Scenarios

Simple Deprovision based on disappearance

The simplest deprovisioning scenario, and the one that can be executed without writing any code, is the “disappearance” scenario.

Here an object (or database line, or text file line) disappears from a source MA and is imported as a delete.

In the Metaverse we have configured our Object Deletion Rule as “Delete Metaverse object when connector from this management agent is disconnected” and selected our source MA.

Finally we have configured our other MAs to delete the CS objects when the Metaverse object is deleted.

In this way we could, for example, delete an AD account because the person’s record disappeared from the HR data source.

Caution: This method may lead to unexpected loss of accounts, temper and job!

As a general rule, it is a bad idea to make destructive decisions based on an absence of information. All sorts of errors, both human and machine, could happen to cause data to be unavailable at the time an Import runs. If you do use this simple approach, only use it for low-priority objects that can be deleted and recreated without much impact.

Deprovision based on attribute change

It is a much better practice to make deprovisioning decisions based on positive data.

So, with the HR data source, we continue to import resigned people, but with a status flag that indicates they are now inactive.

We then write some code in the metaverse extension which reacts to the person’s “inactive” status.

The great advantage to this method is the flexibility it gives us.

For example, we may deal with the person’s connected objects in different ways, deleting contacts and application accounts immediately
but, just disabling the AD user account until further notice.

Deprovisioning a connector space object from metaverse extension code is trivial – all you have to do is add the line

CSEntry.Deprovision()

The bulk of the code before this will be spent in testing attribute values, and connections to different MAs, to determine when conditions are right to issue this command.

Disable then delete

It is simple enough to disable an account using an EAF (see example “Disabling Flow Rules” below).

You could also move the account to a special location (see example “Metaverse Deprovisioning” below).

However what do you do if you want to remove the account at some point in the future?

The first thing to be aware of is you must not delete the metaverse object.

To be able to delete the disabled account in the future it has to be connected to something in the
metaverse.

ILM can only manage connectors.

Next, you will need some kind of datestamp on the metaverse object so your
metaverse extension code will know when it’s OK to delete the account.

The only way to write a value to a metaverse object is with an IAF – so this implies writing the
datestamp outside ILM, on a CDS object, and then importing it back in.

The method in the code examples below works like this:

1. Based on the status attribute in the Metaverse, I export the userAccountControl to disable the AD user account,
2. Based on the same rules, I also export today’s date to the user’s info attribute,
3. II import info back to a metaverse attribute called disableDate,
4. I can then use disableDate in my metaverse extension to decide when the time is right to issue a CSEntry.Deprovision().

There are a couple of points to note about this method:

• While disables will happen on a delta sync, deletions will only happen on a
  full sync.
• The CDS attribute used to hold the date could be modified in the CDS (though you can use this to your advantage if you want to extend the disabled life of an account).

Stop Managing an Object

In some cases object deletion is handled in the CDS itself and all you need to do is to stop managing the object.

In ILM terminology the object becomes a “disconnector” and, while it may still exist in the MA’s connector space, it is no longer connected to a Metaverse object, and ILM can no longer impact it in any way.

To disconnect rather than delete you actually use exactly the same CSEntry.Deprovision() method, but with the correct option selected on your MA’s Configure Deprovisioning page.

You could choose to:

• “Make them disconnectors”. The object is disconnected but remains in the CS and CDS.It will be reassessed for possible joins at each Full Sync,
• “Make them explicit disconnectors”.Like the above, but it will not be reassessed for possible joins, or
• Decide with a Rule Extension (see example “MA Deprovision Sub” below).

The “explicit” option needs a bit more discussion.

If ever you delete and re-import the CS all “explicit” tags will be lost and the objects become regular disconnectors again, and available for joins.

This option should only be chosen in particular circumstances, such as when there is a regular and reliable deletion of redundant objects happening in the CDS.

If you are sure that you will not need to rejoin to an object once it has been disconnected then another idea is to export a blocking attribute before disconnecting.

For example you export the string “Unmanaged” to an attribute on the CDS object, and only disconnect it once the attribute value is confirmed.

You can then use this attribute in a Connection Filter to prevent future re-connections.

Some Common Problems and Questions

I staged some Deletes but I don’t want to export them now

Perhaps there was an error in your code or your import data and you have a bunch of Deletes waiting to go out – but you really don’t want to do that!

Even after correcting the code and re-syncing you may find they turn into Delete-Adds – these should also not be exported as the actual CDS objects will be deleted and recreated – not great for AD accounts!

Unfortunately, the only full-proof fix in this case is a delete and re-import of the connector space.

I have some old accounts with no HR reference – will ILM delete them?

ILM can only delete objects that it is connected to, so if it never connected to the object it can never delete it.

If you plan to tidy up unmanaged objects in your CDS then have a look at the tool csexport.exe (from the MIIS\bin folder) which can be used to export lists of disconnectors.

How can I block an Export if there are too many Disables?

The Export run profile contains an option to stop the job if there are more than a certain number of Deletes queued to go out.

Unfortunately it is not possible to do something similar for disables with native functionality.

If something like this is needed then it should be possible to increment a count in a file from the EAF which deactivates the account, and then modify the script which runs the Export profile to first check the count.

Sideways Joins

A scenario you need to watch out for is what I call a “sideways join”.

Take a situation where the “person” object type has one source MA (eg.: HR) and multiple target MAs (AD, Notes, some other applications).

The source object has been deleted, but one or more of the target objects have remained and are still joined to a
metaverse object.

The problem here is that these objects won’t show up in lists of disconnectors and so can remain, unobserved, for some time.

If deprovisioning logic is based on a value from the source MA then, in a default configuration, this value would have been recalled and is no longer present on the Metaverse object – so your code is probably just skipping it.

When writing your metaverse extension code, it is a good idea to test for unexpected situations – like an object with no connector in the primary source MA – and then throw an error or otherwise deal with the object.

I can see Deletes staged in the connector space, but the objects don’t get deleted in the external system

First, look for error messages in Identity Manager and in the Event Log that may indicate the problem.

Make sure the account used by the MA has the correct permissions in the CDS.

If it’s an “Extensible Connectivity” MA, check that a Delete method has been written in the Connected Data Source Extension.

I disabled an AD user – now how do I remove it from groups?

This is one with no short answer.

You cannot manage the memberOf attribute on AD users as it is a backlinked attribute.

So group membership can only be managed through the member attribute of groups.

This is fine if you are already managing AD groups with ILM – but not ok if they are managed manually in AD.

One of the reasons to keep an account in a disabled state for a while is to allow it to be restored quickly with all its previous rights intact – so removing it from groups may not be the best idea anyway.

If it is necessary then the choices are to fully take over group management with ILM, or to write a script that removes disabled users from groups, and is run outside of ILM.

Code Examples

MA Deprovision Sub

In this example, when the Metaverse object is deleted or disconnected, accounts in the “Student” OU are deleted while accounts in the “Staff” OU become disconnectors.

This sub is located in the Management Agent Extension code.

Public Function Deprovision(ByVal csentry As CSEntry) As DeprovisionAction Implements IMASynchronization.Deprovision
   If csentry.DN.ToString.Contains("OU=Students") Then
      Return DeprovisionAction.Delete
   ElseIf csentry.DN.ToString.Contains("OU=Staff") Then
      ' Optionally, rename the cs object or change attributes
      ' just prior to disconnecting
      Return DeprovisionAction.Disconnect
   Else
      Throw New UnexpectedDataException("DN does not contain " _
      & "'OU=Staff' or 'OU=Students' so I don't know " _
      & "which deprovision action to perform.")
   End If
End Function

Metaverse Deprovisioning

In this example we use the user’s status attribute in the Metaverse to decide if the account should be moved to a “Disabled” OU.

(The actual account disabling is done by an EAF and the disableDate and
userAccountControl are flowed back by IAFs – see below.)

We then use the disableDate attribute on the metaverse object to decide when to perform the final deletion.

This example subroutine has been called from Sub Provision which is located in the Metaverse Extension code.

Private Sub User_Provisioning(ByVal mventry As MVEntry)
   Dim ADMA As ConnectedMA = mventry.ConnectedMAs("MyDomain")
   Dim expectedDN As ReferenceValue
   Dim ShouldExist As Boolean
   Dim DoesExist As Boolean
   Const OU_USERS As String = "OU=Users,OU=MyOrg,DC=mydomain,DC=com"
   Const OU_DISABLED As String = "OU=Disabled,OU=Users,OU=MyOrg,DC=mydomain,DC=com"
   Const KEEP_DISABLED_DAYS As Integer = 90

   '' Should the account exist?
   '' Inactive accounts should exist for KEEP_DISABLED_DAYS after being disabled.
   If mventry("status").IsPresent AndAlso mventry("status").StringValue = "Active" Then
      ShouldExist = True
   Else
      ShouldExist = False

      If MVEntry("userAccountControl").IsPresent AndAlso _
         MVEntry("disableDate").IsPresent Then

         If (MVEntry("userAccountControl").IntegerValue And ADS_UF_ACCOUNTDISABLE) = _
             ADS_UF_ACCOUNTDISABLE Then

            'Account disabled – allow to exist until deletion date
            ShouldExist = True

            Dim disabledDate As DateTime
            disabledDate = Convert.ToDateTime(MVEntry("disableDate").StringValue)
            If Now.Subtract(disabledDate).Days > KEEP_DISABLED_DAYS Then
               ShouldExist = False
            End If
         Else
            'Account enabled
            ShouldExist = True
         End If
      End If
   End If
   '' Check if the AD account already exists
   Select Case ADMA.Connectors.Count
      Case 0
         DoesExist = False
      Case 1
         DoesExist = True
      Case Else
         Throw New UnexpectedDataException("Multiple connectors in MA " & ADMA.Name)
   End Select

   '' Generate the expected DN for the user - to use in renaming or moving
   Dim RDN As String = "CN=" & mventry("displayName").StringValue

   If mventry("status").StringValue = "Active" Then
      expectedDN = ADMA.EscapeDNComponent(RDN).Concat(OU_USERS)
   Else
      expectedDN = ADMA.EscapeDNComponent(RDN).Concat(OU_DISABLED)
   End If

   '' Take action based on values of ShouldExist and DoesExist

   If ShouldExist And DoesExist Then
      'Check if account should be renamed or moved
      Dim CSEntry As CSEntry = ADMA.Connectors.ByIndex(0)
      If CSEntry.DN.ToString.ToLower <> expectedDN.ToString.ToLower Then
         CSEntry.DN = expectedDN
      End If

   ElseIf ShouldExist And Not DoesExist Then
      'Provision Account
      <...>

   ElseIf Not ShouldExist And DoesExist Then
      'Deprovision Account
      CSEntry.Deprovision()

   End If
 End Sub

Disabling Flow Rules

With these flow rules I disable an AD account and also write a date onto the object (I’m using info but you can use any free attribute) to indicate when it was disabled.

I also flow userAccountControl and info back into the metaverse so I have access to the values in my
metaverse extension code (above).

Public Sub MapAttributesForExport(ByVal FlowRuleName As String, ByVal mventry As MVEntry, ByVal csentry As CSEntry) Implements IMASynchronization.MapAttributesForExport

   Const ADS_UF_NORMAL_ACCOUNT As Long = &H200
   Const ADS_UF_ACCOUNTDISABLE As Long = &H2

   Select Case FlowRuleName

      Case "export_userAccountControl"
         Dim currentValue As Long

         If csentry("userAccountControl").IsPresent Then
            currentValue = csentry("userAccountControl").IntegerValue
         Else
            currentValue = ADS_UF_NORMAL_ACCOUNT
         End If

         If mventry("status").IsPresent AndAlso mventry("status").Value = "Active" Then
            ' Enable account
            csentry("userAccountControl").IntegerValue = _
            (currentValue Or ADS_UF_NORMAL_ACCOUNT) And (Not ADS_UF_ACCOUNTDISABLE)

         Else
            ' Disable account
            csentry("userAccountControl").IntegerValue = _
            currentValue Or ADS_UF_ACCOUNTDISABLE
         End If

      Case "export_info"
         If mventry("status").IsPresent AndAlso mventry("status").Value = "Active" _
            AndAlso csentry("info").IsPresent Then
            csentry("info").Delete()
         ElseIf mventry("status").Value = "Inactive" AndAlso _
            Not csentry("info").IsPresent Then
            csentry("info").StringValue = Now.ToString
         End If

      End Select
End Sub

XMA Delete Method

For an MA of type “Extensible Connectivity” you need to write your own routines for the export types
Add, Modify and Delete.

This example shows the Delete step for an XMA which manages home folders for user accounts.

The sub is found in the Connected Data Source Extension.

This example is a very simple deletion of the folder, but you could easily add extra code to, for example, move the folder to an archive location.

(If you want to see an example of the Add method see my blog:
Creating Home Directories)

 Public Sub ExportEntry(ByVal modificationType As ModificationType, ByVal changedAttributes As String(), ByVal csentry As CSEntry) Implements IMAExtensibleCallExport.ExportEntry

If modificationType = Microsoft.MetadirectoryServices.ModificationType.Add Then
' Create the folder

ElseIf modificationType = _
Microsoft.MetadirectoryServices.ModificationType.Delete Then
System.IO.Directory.Delete(csentry("path").StringValue, True)
End If

End Sub

About the Author

Carol Wapshere has been working in IT since 1990, and has since worked in many different organizations, across four different countries. She started out in Netware then moved into Microsoft server products, picking up an assortment of skills in other non-Microsoft systems along the way. She first started working with MIIS in 2005 and loved how it could be used to tie together disparate systems, bringing in much-needed order, and making lots of tedious jobs just disappear.

Thanks to Markus Vilcinskas and Peter Geelen for their help with this document.

Warning: I will have to revisit this post – as I haven’t yet installed Exchange 2010 in a production environment the Exchange comments are based on reading rather than hands-on experience, and in particular I’m unsure about the management of email-enabled Security groups.

http://social.technet.microsoft.com/Forums/en-US/identitylifecyclemanager/thread/f8ad045d-7252-4cd1-a189-d704a8f99129

The article covers various management tasks you can acheive with the standard AD MA, including provisioning and updating of users, mailboxes, contacts and distribution groups. There are quite a few code samples as well.

Managing Exchange 2000/2003/2007 with ILM 2007

This article covers the management of Exchange-enabled objects using the native Active Directory Management Agent that is included with ILM 2007 FP1.

The managed object types discussed are Users, Contacts, Groups and Dynamic Distribution Lists. The article also covers the special cases of adding mailboxes to existing accounts, and supporting a Resource Forest. Where extra steps are required for Exchange 2007 this has been highlighted.

It is assumed that the reader is comfortable with the concepts of Provisioning code and Advanced attribute flow rules.

Permissions

The service account used in the connection properties of the Management Agent must have sufficient rights to execute the required changes in AD.

Typically a Domain Admin account will be used, but if this is not permitted in your environment you will need to do some testing. The minimum permissions required are:

• Replicate Directory Changes
• Rights to create/delete/modify objects in the specific OUs
• Exchange Administrator (2003) or Exchange Recipient Administrator (2007)

Users

Provisioning Mail Users

Exchange 2000/2003

Provisioning a mail user is most simply done using the CreateMailbox method of the ExchangeUtils class. This method will create a new user account, and populate the necessary mail attributes for you.

See the code sample Create a User with a Mailbox at the end of this document for an example of the provisioning code.

Mixed Exchange 2003 and 2007

In a mixed environment the RUS still runs so Exchange 2003 methods may be used. Make sure that you do not tick the “Enable Exchange 2007 provisioning” box in the Management Agent configuration.

Exchange 2007

The same code will work when provisioning to Exchange 2007, however there are some extra requirements for the ILM server:

• ILM 2007 FP1 or later
• Powershell
• Exchange 2007 Management Tools
• Latest rollup packs on Exchange and ILM servers

In addition you must tick Enable Exchange 2007 provisioning on the Extensions tab of the Management Agent.

Adding a Mailbox to an existing User

Sometimes you may need to create a mailbox for an existing account. As the account already exists this is not actually a provisioning task, and is therefore handled with export flow rules.

All you need to do is to populate the following attributes, in addition to the basic user attributes:

• displayName – if not already set
• mailNickname – with the local part of the email address (the bit before the “@”)
• homeMDB – with the DN of the mail store
• mDBUseDefaults – set to “True” to use the default quota settings

Special Mailbox Types

Exchange 2007 includes some extra mailbox types:

• Room Mailbox,
• Equipment Mailbox,
• Linked Mailbox.

The Linked Mailbox is covered in the Resource Forest section below.

The Room and Equipment mailboxes are currently not supported by ILM 2007 provisioning. The only reliable method is to create a User Mailbox using ILM 2007, and then use the set-mailbox cmdlet to change the mailbox type.

Troubleshooting

Export Errors

The most common problems with provisioning Exchange users will relate to permissions. Make sure that the account used by the MA to connect to AD has permission to create Exchange users. Also make sure you have the latest service packs and rollups on the Exchange and ILM servers – at least SP1 RU9.

Where’s the Mailbox?

Exchange does not create the actual mailbox until it is opened or something is sent to it, therefore it is completely normal for no new mailboxes to be listed directly after the ILM export.

To confirm if the user is really mail-enabled:

• In Exchange 2003, check that the user’s Exchange tabs have appeared in the Exchange-enhanced version of AD Users & Computers.
• In Exchange 2007, use the get-user cmdlet to confirm the user’s object type is “UserMailbox”, or check that they appear as a Recipient in the Management Console.

Exchange 2007 and Global Catalog targeting

There is a known problem with Exchange 2007 provisioning and AD replication delays. On the MA’s Configure Directory Partitions tab you can hard-code the name of a preferred domain controller. Enter the name of the nearest Global Catalog to ensure that both the user creation and the mailbox creation are performed in the same place.

Note
Use the Resource Kit utility nltest to find Global Catalog servers: nltest /DSGETDC:mydomain.com /GC

Modifying Mail Users

You can change a user’s Exchange related attributes using export flow rules.

The following table is not exhaustive. If you wish to automate an Exchange modification the best thing to do is make the change manually and then inspect the attribute changes using ADSIEdit.
In this way you can discover which attributes you need to create flow rules for, and the types of value you should flow.

Resource Forest

In a Resource Forest scenario the following accounts are needed:

1. An enabled user account in the Account Forest.
2. A disabled account in the Resource Forest with an attached mailbox.

The account creation in the two forests and the mailbox linking are simple enough to achieve with ILM. A provisioning code sample has been included at the end of this document under Create Account Forest and Resource Forest Accounts.

The difficulty comes with the permissions assignment piece of the puzzle – it is necessary for the user’s account to have the Full Access and Send As rights to the mailbox. This is not something that is possible with the native Active Directory MA.

While there are several ways to solve the permissions-assignment problem, the typical way is to run a script after the export step. The script might simply trawl AD looking for accounts to update or it could read details from the ILM export log and target the new accounts.

While outside the scope of this document, the following resources have been included for reference:

1. A Microsoft technote showing how to Script Exchange 2000/2003 mailbox permissions,
2. A PowerShell script for Exchange 2007 has been included in the Code section at the end of this article.

Contacts

Contacts are used for two primary functions in Exchange, both of which can be automated with ILM:

1. Adding organization-wide contacts to the Global Address List.
   ILM could be used to import information from a CRM system and automatically create the contact object.
2. As a way to forward mail from a mailbox within the organization.
   Some organizations (such as universities) allow users to forward their mail to another address. As long as ILM has the information about the forwarding request (perhaps entered by the user in a self-service portal) it can be configured to create the contact and set up the forwarding.

Provisioning

Contacts may be provisioned very simply using the CreateMailEnabledContact method from the ExchangeUtils class.
See the code sample Create a Contact at the end of this document for an example of the provisioning code.

Modifying

Distribution List

There are three types of Distribution list in Exchange:

1. Groups of type Distribution
2. Groups of type Security that have an email address
3. Dynamic distribution lists.

All three types can be created and managed with ILM, but the processes will differ.

Distribution Groups

To provision a standard Distribution Group use the CreateDistributionList method of the ExchangeUtils class. See Create a Distribution List at the end of this document for a code sample.

The main modification you will do with groups is to update the membership list. Group population is outside the scope of this document, though it is worth looking into Group Populator and Multi-Value tables.

Security Groups with Email Address

It is possible to mail-enable a Security group, allowing it to then also act as a distribution list.

Provisioning such a group is a simple matter of creating a security group and adding the mail address. See Create a Mail-Enabled Security Group under Code Samples at the end of this document.

Dynamic Distribution Lists

You may also use ILM to provision Dynamic Distribution Lists. All you need to do is to create an object of type msExchDynamicDistributionList and add values to the following attributes:

• displayName
• mailNickname
• msExchDynamicDLFilter
• msExchDynamicDLBaseDN

See Create a Dynamic Distribution List under Code Samples at the end of this document.

Code Samples

Create a User with a Mailbox

This MVExtension code is in addition to export flow rules to the user object type on the following attributes:

• displayName
• givenName
• sAMAccountName
• sn
• userPrincipalName

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Const ADS_UF_NORMAL_ACCOUNT As Integer = &H200

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim homeMDB As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "person"

    MA = mventry.ConnectedMAs("MYDOMAIN")

    If <test that account should exist> AndAlso MA.Connectors.Count = 0 Then

      rdn = "CN=" & mventry("sn").Value & ", " & mventry("givenName").Value

      dn = MA.EscapeDNComponent(rdn).Concat("OU=Users,OU=MyOrg, " _

                                            & "dc=mydomain,dc=local")

      mailNickname = mventry("mailNickname").Value

      ' The following line assumes MDB, SG and MailServer have been

      ' populated for the user in the Metaverse.

      homeMDB = "CN=& mventry("MDB").StringValue _

         & ",CN=" & mventry("SG").StringValue _

         & ",CN=InformationStore,CN=" & mventry("MailServer").StringValue _

         & ",CN=Servers,CN=Exchange Administrative Group (FYDIBOHF23SPDLT)" _

         & ",CN=Administrative Groups,CN=First Organization" _

         & ",CN=Microsoft Exchange,CN=Services,CN=Configuration" _

         & ",DC=mydomain,DC=local"  

      csentry = ExchangeUtils.CreateMailbox(MA, dn, mailNickname, homeMDB)

      csentry.DN = dn

      csentry("unicodePwd").Values.Add("FirstP@ssw0rd")

      csentry("userAccountControl").IntegerValue = ADS_UF_NORMAL_ACCOUNT

      csentry.CommitNewConnector()

    End If

  End Select

End Sub

Create Account Forest Accounts and Resource Forest Accounts

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Const ADS_UF_NORMAL_ACCOUNT As Integer = &H200

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim homeMDB As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "person"

    'Create Account Forest account - no mailbox

    MA = mventry.ConnectedMAs("AccountForest")

    If MA.Connectors.Count = 0 Then

      rdn = "CN=" & mventry("sn").StringValue _

                  & ", " & mventry("givenName").StringValue

      dn = MA.EscapeDNComponent(rdn).Concat("OU=Users,OU=MyOrg, " _

                                            & "dc=accountdomain,dc=local")

      csentry = MA.Connectors.StartNewConnector("user")

      csentry.DN = dn

      csentry("unicodePwd").Values.Add("FirstP@ssw0rd")

      csentry("userAccountControl").IntegerValue = ADS_UF_NORMAL_ACCOUNT

      csentry.CommitNewConnector()

    End If

    'Create disabled account and mailbox in Resource forest. 

    '  This can only be done once the objectSID from the account domain 

    '  is available. Create a metaverse Binary attribute called SID

    '  and flow objectSid -> SID.

    '  The account is disabled because no password is set. Alternatively set

    '  a random password and disable using userAccountControl.

    MA = mventry.ConnectedMAs("ResourceForest")

    If MA.Connectors.Count = 0 AndAlso mventry("SID").IsPresent Then

      rdn = "CN=" & mventry("displayName").StringValue

      dn = MA.EscapeDNComponent(rdn).Concat("OU=LinkedMailboxes,OU=MyOrg, " _

                                            & "dc=resourcedomain,dc=local")

      mailNickname = mventry("mailNickname").StringValue

      homeMDB = "CN=" & mventry("MDB").StringValue _

         & ",CN=" & mventry("SG").StringValue _

         & ",CN=InformationStore,CN=" & mventry("MailServer").StringValue _

         & ",CN=Servers,CN=Exchange Administrative Group (FYDIBOHF23SPDLT)" _

         & ",CN=Administrative Groups,CN=First Organization" _

         & ",CN=Microsoft Exchange,CN=Services,CN=Configuration" _

         & ",DC=mydomain,DC=local"  

      csentry = ExchangeUtils.CreateMailbox(MA, dn, mailNickname, homeMDB)

      csentry.DN = dn

      csentry("msExchMasterAccountSid").BinaryValue = mventry("SID").BinaryValue

      'The following setting is optional but can help with tracking the mailbox user.

       csentry("extensionAttribute1").Value = "accountdomain\" _

                                              & mventry("uid").StringValue

       csentry.CommitNewConnector()

     End If

  End Select

End Sub

Assign Resource Mailbox Permissions – Exchange 2007, powershell

The following script assigns the FullAccess and SendAs permissions to a resource forest mailbox.
The resource forest account needs to have the domain\username of the user’s actual account written to extensionAttribute1, as per the provisioning code above.

$Filter = "(&(ObjectCategory=user)(extensionAttribute1=*))"

$Searcher = New-Object System.DirectoryServices.DirectorySearcher($Filter)

$Searcher.Findall() | Foreach-Object -Process {

$alias = [string]$_.properties.item("mailNickname")

$user = [string]$_.properties.item("extensionAttribute1")

Add-MailboxPermission -Identity $alias -AccessRights FullAccess, SendAs -User $user

}

Create a Contact

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "person"

     MA = mventry.ConnectedMAs("MYDOMAIN")

     If MA.Connectors.Count = 0 Then

       rdn = "CN=" & mventry("displayName").StringValue

       dn = MA.EscapeDNComponent(rdn).Concat("OU=Contacts,OU=MyOrg, " _

                                            & "dc=mydomain,dc=local")

       mail = mventry("mail").StringValue

       'The mailNickname is only for internal Exchange purposes.

       'You could just as easily use an id number from the source data.

       mailNickname = mventry("mail").Value.Split("@")(0)

       csentry = ExchangeUtils.CreateMailEnabledContact(MA, dn, mailNickname, mail)

       csentry.DN = dn

       csentry.CommitNewConnector()

    End If

  End Select

End Sub

Create a Distribution List

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "group"

    MA = mventry.ConnectedMAs("MYDOMAIN")

    If MA.Connectors.Count = 0 Then

      rdn = "CN=" & mventry("cn").StringValue

      dn = MA.EscapeDNComponent(rdn).Concat("OU=Groups,OU=MyOrg, " _

                                            &"dc=mydomain,dc=local")

      mailNickname = mventry("mailNickname").StringValue

      csentry = ExchangeUtils.CreateDistributionlist(MA, dn, mailNickname)

      csentry.DN = dn

      csentry.CommitNewConnector()

    End If

  End Select

End Sub

Create a Mail-Enabled Security Group

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "group"

    MA = mventry.ConnectedMAs("MYDOMAIN")

    If MA.Connectors.Count = 0 Then

      rdn = "CN=" & mventry("cn").StringValue

      dn = MA.EscapeDNComponent(rdn).Concat("OU=Groups,OU=MyOrg, " _

                                            & "dc=mydomain,dc=local")

      mailNickname = mventry("mailNickname").StringValue

      csentry = MA.Connectors.StartNewConnector("group")

      csentry("groupType").Value = -2147483640  'Universal Security

      csentry("displayName").Value = mventry("cn").StringValue

      csentry("mailNickname").Value = mailNickname

      csentry.DN = dn

      csentry.CommitNewConnector()

    End If

  End Select

End Sub

Create a Dynamic Distribution List

This MVExtension code snippet creates Department DDLs.
The department names have been imported into department objects in the Metaverse.
The users’ department attribute matches exactly the department names.

Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision

  Dim csentry As CSEntry

  Dim MA As ConnectedMA

  Dim dn As ReferenceValue

  Dim rdn As String

  Dim mailNickname As String

  Dim mail As String

  Select Case mventry.ObjectType

  Case "department"

    MA = mventry.ConnectedMAs("MYDOMAIN")

    If MA.Connectors.Count = 0 Then

      rdn = "CN=" & mventry("cn").StringValue

      dn = MA.EscapeDNComponent(rdn).Concat("OU=DDLs,OU=MyOrg, " _

                                            & "dc=mydomain,dc=local")

      mailNickname = mventry("mailNickname").StringValue

      csentry = MA.Connectors.StartNewConnector("msExchDynamicDistributionList")

      csentry.DN = dn

      csentry("displayName").Value = mventry("cn").StringValue

      csentry("mailNickname").Value = mailNickname

      'The following filter selects users whose department equals the DDL cn

      csentry("msExchDynamicDLFilter").Value = "(&(!cn=SystemMailbox{*})" _

         & "(&(&(&(& (mailnickname=*)" _ 

         & "(| (&(objectCategory=person)(objectClass=user)" _

         & "(|(homeMDB=*)(msExchHomeServerName=*))) )))" _

         & "(objectCategory=user)(department=" _

         & mventry("cn").StringValue & "))))"

      csentry("msExchDynamicDLBaseDN").Value = "OU=Groups,OU=MyOrg, " _

                                            & "dc=mydomain,dc=local"

      csentry.CommitNewConnector()

    End If

  End Select

End Sub

ILM Forum Threads

• Provisioning Exchange 2007 with ILM 2007
• ILM With FP1 and Exchange 2007
• Exchange 2007 ‘Shared’ Mailbox Provisioning with ExchangeUtils
• Attribute List for Exchnage 2003

About the Author

Carol Wapshere has been working in IT since 1990, and has since worked in many different organizations, across four different countries. She started out in Netware then moved into Microsoft server products, picking up an assortment of skills in other non-Microsoft systems along the way. She first started working with MIIS in 2005 and loved how it could be used to tie together disparate systems, bringing in much-needed order, and making lots of tedious jobs just disappear.

Thanks to Markus Vilcinskas and Peter Geelan for their help with this document.

http://www.wapshere.com/missmiis

But we don’t need to be that fancy. If all you want is to create a regular Windows-type home folder, at the same time as you create the AD user account, then here’s a way to do with an XMA.

Overview

To summarise the approach:

1. Create the user account in AD,
   • Flow the SID back into the metaverse – proof the account exists,
2. Create the home folder using an XMA,
   • Flow the path back into the metaverse,
3. Flow the path out to the user’s homeDirectory attribute through the AD MA.

Metaverse Schema

Add the following two attributes to the “person” type (or whatever you are using for your user objects):

• userSid (Binary)
• homeDirectory (String)

Create the XMA

Create an Extensible MA and call it “HomeFolders”. (Note: I don’t use spaces in my MA names so I have no scripting hassles.)

Configure Connection Information

Choose “Import and Export” and “Call based”.

Connected data source extension: “HomeFolders_CSExtension.dll”  (we will create the extension later)

Connection information: If you want to use this you will have to work out how to use the logon details in your CSExtension code to force the Import and Export steps to use this account instead of the ILM service account. I’m no great programmer, and to this day I’ve always managed to get away with giving the ILM service account the permissions I need. In this case it needs permission to create home folders and set ACLs.

Configure Additional Parameters

None

Select Template Input File

I created a text file called homefolders.txt and saved it to the MaData folder. In the file I have the following line:

path,folder,server,owner

Select the file and choose “Delimited” as the file type.

It is useful to keep this template file. Later, if you need to change the schema, you can modify this file and use it in the Refresh Schema operation.

Delimited Text Format

Tick “Use first row for header names”.

Select “Comma” as the delimiter.

Configure Attributes

Set Anchor: path

I also click Advanced and change the Fixed object type to “folder”.

Define Object Types

Leave on the default – only path is required.

Connector Filter

None. Use this if there are certain folder names you want to exclude.

Join and Projection Rules

If you’re lucky the folder names will match the sAMAccoutNames and you can join on that. You could also flow homeDirectory back from the AD MA and join on the path.

Try very hard to avoid manual joins in such an MA as you have no real way to flow an identifier back out to the folder itself (something you should always do if manual joins have been used – you should always be able to clear and re-import a connector space). If you have to go the manual join way then consider using a SQL table alongside this MA, as in this post, to keep track of folder owners.

Attribute Flow

One inbound flow only:

path --> homeDirectory

Configure Deprovisioning

“Make them disconnectors”

You can delete home folders with an XMA – you just need to add the appropriate code in your CSExtension to deal with modificationType = delete. But for this example I’m just creating the folder.

Configure Extensions

Click Finish to create the MA.

Write the CSExtension

With the new MA selected, click on Create Extension Project. In Project type choose “Connected Data Source Extension” and then enter as the name “HomeFolders_CSExtension”. Make sure your Project Location is correct and then click OK.

GenerateImportFile

The first step is to write the Import step. This should go out and find all the existing home folders and then populate a csv file along the lines of the template you created above. The actual import into the connector space then occurs from the csv file.

Note that my GetOwner function is a fudge – I actually just return the first domain account that I find with rights to the folder. This is acceptable to me because I am not going to use this MA to modify existing rights. All I really care about is checking that the user was correctly assigned to a newly created home folder. Typically the user will be the only domain account with explicit (as opposed to inherited) rights to the folder, so this should work fine.

  Dim Servers As String() = {"server1", "server2", "server3"}

    Public Sub GenerateImportFile(ByVal filename As String, ByVal connectTo As String, ByVal user As String, ByVal password As String, ByVal configParameters As ConfigParameterCollection, ByVal fullImport As Boolean, ByVal types As TypeDescriptionCollection, ByRef customData As String) Implements IMAExtensibleFileImport.GenerateImportFile
        Dim server As String
        Dim path As String
        Dim folders As System.Collections.IEnumerator
        Dim fw As StreamWriter

        Try
            'Open the output file specified in the run profile
            fw = New System.IO.StreamWriter(filename, False)
            fw.WriteLine("path,folder,server,owner")
        Catch ex As Exception
            Throw New UnauthorizedAccessException("Unable to open file: " & filename)
        End Try

        For Each server In Servers
            folders = Directory.GetDirectories("\\" & server & "\homedir").GetEnumerator
            While folders.MoveNext
                path = folders.Current.ToString
                'For each folder, write an entry into the import file
                fw.WriteLine(path & "," _
                            & path.Split("\".ToCharArray)(4) & "," _
                            & path.Split("\".ToCharArray)(2) & "," _
                            & GetOwner(path))
            End While
        Next
        fw.Close()
    End Sub

   Function GetOwner(ByVal path As String) As String
        ' This function does not get the actual owner of the folder,
        ' rather it returns the first domain trustee account.
        ' This is not very precise but the purpose is just to check the ACL
        ' for new folders so it will do.
        Dim AccessRules As AuthorizationRuleCollection
        Dim AuthRule As AuthorizationRule = Nothing
        Dim Owner As String = ""
        Dim Fs As FileSecurity

        Try
            Fs = New FileSecurity(path, AccessControlSections.Access)
            AccessRules = Fs.GetAccessRules(True, False, Type.GetType("System.Security.Principal.NTAccount"))
            If Not AccessRules Is Nothing Then
                For Each AuthRule In AccessRules
                    If AuthRule.IdentityReference.ToString.IndexOf("MYDOMAIN\") = 0 Then
                        Owner = AuthRule.IdentityReference.ToString
                        Exit For
                    End If
                Next
            End If
        Catch ex As Exception
        End Try

        If AuthRule Is Nothing Or _
           Owner = "" Or _
           Owner.IndexOf("MYDOMAIN\") < 0 Then
            Return ""
        Else
            Return Owner
        End If

    End Function

Once this code is in place you should be able to run an Import step on your MA. You will need to specify an import file name – just something like “import.csv” is fine. Once your code is working you will be able to see the file created in the MaData\HomeFolders directory, and populated with information about the folders it has found.

ExportEntry

I’m going to include the code for the ExportEntry sub here, but we won’t have anything to export until we modify our MVExtension provisioning code to create new folder objects. More on that below.

    Public Sub ExportEntry(ByVal modificationType As ModificationType, ByVal changedAttributes As String(), ByVal csentry As CSEntry) Implements IMAExtensibleCallExport.ExportEntry

        If modificationType = Microsoft.MetadirectoryServices.ModificationType.Add Then
            Directory.CreateDirectory(csentry("path").StringValue)

            If Directory.Exists(csentry("path").StringValue) Then
                Try
                    ' Get current ACL from the folder
                    Dim security As DirectorySecurity = Directory.GetAccessControl(csentry("path").StringValue)

                    ' Create a new rule granting owner full access
                    Dim rule As New FileSystemAccessRule(New NTAccount(csentry("owner").StringValue.ToLower), FileSystemRights.FullControl, AccessControlType.Allow)

                    ' Add the rule to the existing rules
                    security.AddAccessRule(rule)

                    ' Persist the changes
                    Directory.SetAccessControl(csentry("path").StringValue, security)

                Catch ex As Exception
                    ' If the ACL failed the delete the folder so the operation can be retried later.
                    Directory.Delete(csentry("path").StringValue)
                    Throw New EntryExportException("Failed to set ACL on " & csentry("path").StringValue _
                              & " - deleting folder. " & vbCrLf & ex.Message)
                End Try

            End If
        End If

    End Sub

Provisioning

Now we want to create the home folder.

As I indicated at the top of this post, you need some kind of proof that the user account was created before you create the home folder. The reason is permissions – you can’t grant permissions to a user that doesn’t exist yet. Technically you could provision your user and home folder objects at the same time, so long as you made sure the AD MA was exported first, but fundamentally I don’t like this. Even though it means running a series of export/import-syncs in a row, I much prefer to wait for the user account before I provision the home folder.

And the way I do this is by checking the Sid. I flow the userSid back into the Metaverse from the AD MA and use this as a test in my provisioning logic for home folders.

  Sub HomeFolder_Provisioning(ByVal mventry As MVEntry)
        Dim HFMA As ConnectedMA = mventry.ConnectedMAs("HomeFolders")
        Dim path As String = ""
        Dim server As String = ""

        '' Generate the path based on location
        If mventry("location").IsPresent Then
            Select Case mventry("location").StringValue.ToLower
                Case "london"
                    server = "server1"
                Case "zürich"
                    location = "server 2"
                Case Else
                    server = "server3"
            End Select
            path = "\\" & server & "\homedir\" & mventry("uid").StringValue
        End If

        '' Should the folder exist? AD account must be provisioned first.
        '' Note: Folders are NOT deleted. ShouldExist = FALSE just prevents creation.
        If mventry("Sid_AD").IsPresent Then
            ShouldExist = True
        Else
            ShouldExist = False
        End If

        '' Check if the folder already exists
        Select Case HFMA.Connectors.Count
            Case 0
                DoesExist = False
            Case 1
                DoesExist = True
            Case Else
                Throw New UnexpectedDataException("The metaverse person object with employeeID =" _
                 & mventry("employeeID").StringValue & " has more than one connector in MA " & HFMA.Name)
        End Select

        '' Take action based on values of ShouldExist and DoesExist
        If ShouldExist And DoesExist Then
            'Do nothing

        ElseIf ShouldExist And Not DoesExist Then
            'Create folder object in CS
            Dim csentry As CSEntry = HFMA.Connectors.StartNewConnector("folder")
            csentry("path").Value = path
            csentry("server").Value = server
            csentry("folder").Value = mventry("uid").StringValue
            csentry("owner").Value = "MYDOMAIN\" & mventry("uid").StringValue
            csentry.CommitNewConnector()

        ElseIf Not ShouldExist And DoesExist Then
            'Do nothing

        Else 'Should not exist and does not exist
            'Do nothing
        End If

    End Sub

All going well, you should now be able to Sync your AD MA, and any AD accounts that are missing a home folder should have one provisioned.

Start testing your exports by restricting the Export step to only process one object at a time.

Update User homeDirectory

The final step is to flow the path out to the homeDirectory attribute on the user, using the AD MA.

homeDirectory --> homeDirectory

If you want to map a particulay drive letter at the same time then flow a constant to homeDrive, eg.,

"H:" --> homeDrive

Doing more

You can do more. As I mentioned above you could modify your ExportEntry sub to process a delete, and then delete the home folder – though you would want to tread very carefully. There are bound to be far more interesting things you can do with the permissions, or with sharing the folder – but I’ll leave that for you to work out. Unless I have to do something like that myself – and then I will no doubt write it up here.

Event Type:    Error
Event Source:    MIIServer
Event Category:    Server
Event ID:    6801
Date:        15.09.2009
Time:        10:14:02
User:        N/A
Computer:    ILMSERVER
Description:
The extensible extension returned an unsupported error in MIIS.
The stack trace is:

"Microsoft.MetadirectoryServices.ExtensionException:
**** ERROR ****

ExternalEmailAddress is mandatory on MailUser.

**** END ERROR ****

**** ERROR ****

The mail contact and mail user must have a valid external e-mail address.

**** END ERROR ****

at Exch2007Extension.Exch2007ExtensionClass.AfterExportEntryToCd(Byte[] origAnchor, String origDN, String origDeltaEntryXml, Byte[] newAnchor, String newDN, String failedDeltaEntryXml, String errorMessage)
Microsoft Identity Integration Server 3.3.0118.0"

This event had been asked about on the Technet forum, but the answers talked about rollup versions – and I had RU9 on both the Exchange and ILM servers.

Eventually I figured out there was a typo in my homeMDB string. The clue was that all the expected mail attributes were populated in AD, except homeMDB.

Now what “ExternalEmailAddress” has to do with homeDMB I do not know!

However, in  a recent thread on the Technet forum, Michael D’Angelo listed all the attributes that he has found are needed for an Exchange 2007 mailbox. I eventually managed to test this myself in a lab and, surprisingly, it now seems to be working perfectly – and in fact I only needed to populate the same attributes as for Exchange 2003. These are:

displayName
mailNickname
homeMDB
mDBUseDefaults

I was using Exchange 2007 rollup 9 in the lab. Not sure if anything has changed with the rollups to make it work now.

Note: this post was modified on the 24/7/09 as I prefer the posts to represent what I think is correct now instead of what I thought was correct at the time.