Microsoft FIM: Working with Domino Connector v8
Posted on July 22, 2013 by Michael Pearn — 4 Comments
Rate This
We don’t always work with all of the ‘latest’ or ‘bleeding edge’ software here at Kloud, and occasionally us Identity Management consultants have to delve into the past and use some knowledge once thought lost from the world. Okay, so it’s not that bad, but I did find myself having to work with IBM Domino Server version 8 and FIM R2′s ECMA based Lotus Domino Management Agent (or ‘Connector’ in the new language) for a bi-directional sync between Domino and Active Directory (Exchange, Lync etc.).
The Technical Reference document supplied with the Connector from Microsoft is good (http://technet.microsoft.com/en-us/library/hh859750(v=ws.10).aspx), but not perfect and in my opinion is probably missing about 10% of the information required to get an import and export working with the connector.
There’s some key information missing from the document, at least in terms of interpreting ‘error codes’ because when you run into errors (and I’d be amazed if you didn’t!), there isn’t much guidance interpreting the errors that appear on the Microsoft FIM server side of things. Also, there’s very little in the way of guidance for those that have had to use Sync. Rules to import/export from Domino 8.
I’ll split this up into a few sections – first will be to verify the Notes side of things in terms of client installation and FIM/Domino server side requirements. The second section will be listing the errors I encountered (interpreted as a Microsoft FIM expert, not Domino remember!) and the actions I needed to follow up with the Domino expert to get the Connector working in both directions.
Installing the Notes Client
The guidance is actually very good in the MS document and be sure to follow it to the letter, particularly the guidance around which features to install (don’t forget to specify to install the ‘Client Single Logon Feature’ as it’s not default!). Also, when you’re installing the Lotus Client be sure to specify that you’re installing it for a ‘single user‘ only and ensure the ‘Data’ folder does NOT get created under the ‘Application Data’ folder:
For my customer, I installed everything under one very basic path: <Install drive>:\IBM\Lotus\Notes, and ensured my data folder was under: <Install drive>:\IBM\Lotus\Notes\Data. Your installation should look similar to the following (click to enlarge):
I then applied ‘full control’ permissions to my FIM Synchronisation service account to the <Install drive>:\IBM\Lotus\ folder.
For any of my .ID files that I needed to use (minimum 1 for importing only, minimum 2 for importing & exporting), I then copied these to the <Install drive>:\IBM\Lotus\Notes\Datafolder. There’s guidance out there to suggest that you need to install Lotus Notes logged in as the Synchronization Service. This is not required in my experience and actually breaks Microsoft ‘best practice’ which denies allowing the Sync. service console login rights.
Check indexing and ACLs in Lotus Notes
In my career, I’ve often been told ‘yep! That’s been done’ by all sorts of people. I don’t take everything at face value and prefer to check everything myself. One of the critical requirements to get the Connector working is to ensure that ‘indexing’ has been applied to the Names.nsf.
- Open Lotus Notes and first create a Workspace Icon for the Address book in question and then open the Domino Directory (names.nsf).
- Check the existence of indexing by browsing to: File àApplication Properties and click the ‘magnifying glass’ icon to verify that database has had a recent index applied to it. Check the ‘update frequency (servers only)’ is set to ‘immediate’:
3. Check to ensure your account has the correct ACLs by browsing to: File à Access Control. Locate your account in the list and select it. On the right, you can verify the correct permissions (click to expand):
Sync Rules
The following images highlight an example of ‘export Sync. Rules’, in particular the ‘initial flow’ values that you supply when you only ‘create’ (export) a person from FIM to Domino. Your ‘Organization value i.e.: O=Org’ will be particular to your Domino environment (click to enlarge):
Note, the key part of my guidance is using ‘comma’ separate values for the Distinguished Name (DN) requirement. Previous Visual Basic and C# .NET code made sure you used ‘forward slashes’ for the DN value (e.g. CN=Michael Pearn/O=Org,NAB=names.nsf). In my experience, this does not work and all values should be comma separated. Be very wary of using this sample code for the Domino v8 connector (I’ve tried and failed):http://msdn.microsoft.com/en-us/library/windows/desktop/ms696023(v=vs.85).aspx
Enable Domino Connector Logging
It’s vital that you enable the Synchronization Service logging created at: <program files>\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions\LotusDominoConnector.txt.
At a minimum, set the log file value to ’3′ (in the logging.xml file in the same Extension folder) to capture all events and detail. The next few sections will refer to the error strings that were present in this log.
Troubleshooting Errors
Error #1: “Unable to retrieve schema. Error: An anchor attribute defined by the extension must not be of type Reference or Boolean. A multivalued attribute defined by the extension must not be of type Boolean”
In hindsight, this is an obvious error however if you attempt to connect to Domino without checking your ACLs or Indexing, then you will be bound to get this error at some stage.
Stop, down tools and talk to your Domino admin. There is no way to fix this issue from the FIM side of things. If you see any errors between the “Connectivity” and “Global Parameters” page then check:
- Your ID account you are using has the proper permissions to the Names.NSF you are connecting to as per the guidance earlier.
- You have a good names resolution and IP ping network connection to the Domino server. Domino relies a lot on resolving NetBIOS names to the server, so troubleshooting DNS will do no good here. Also, be wary of trying to use a ‘laptop lab’ (as I call them) whereby you’re trying to use a personal Hyper-V lab connecting to a production infrastructure. For the life of me I could not get my lab connecting to a Domino server so shifted my testing to a network connected server and this solved 90% of my connectivity problems. I’d strongly recommend using a dedicated testing FIM server for any kind of Domino import/export testing.
- Ensure indexing is applied as per the guidance earlier.
Verify this connection is working and potentially error free by checking the ‘Time Zone’ information on the “Global Parameters” page of the Domino Connector properties. If it is blank, then there are connectivity problems which need to be resolved before continuing.
Error #2: “Invalid-Provisioning-attribute-value”
Buried in the Microsoft guidance is the sentence ‘You should have the O/OU certifier Id and the password to register a particular user in the Organization / Organization Unit”. This is a very key point and I overlooked it when I first started working. This setting is actually (unhelpfully) located at the bottom of the ‘Global Parameters’ section of the Domino Connector properties:
Imports will work fine without specifying a value here, however your Domino server will require the ID file used to create objects for that ‘Certifier’ (and don’t ask me what that means!). If you neglect to specify the ID file and password here, then you will see an error in the Metaverse export run as ‘Invalid-Provisioning-attribute-value’, and your error will appear in the log as:
————————————————————————————————————————
2013-07-16T16:53:23 [1768:6028] Trace – DominoPerson:RegisterUser : “Domino” – certkey :
2013-07-16T16:53:23 [1768:6028] Trace – DominoPerson:RegisterUser : “Domino” -certkey is missing.
2013-07-16T16:53:23 [1768:6028] Trace – Person:Add : “Domino” – UniversalID :
2013-07-16T16:53:23 [1768:6028] Trace – LotusDominoMA:PutExportEntries : “Domino” – Call ended
————————————————————————————————————————
Error #3: “Required attribute ‘UniversalID’ is missing”
I’ve seen a few people post on the Internet their concerns that when they get an issue exporting to Domino, if they click in the Sync engine ‘Validate object against schema’, they get an error message: ‘UniversalID is missing’. While it’s true the connector uses UniversalID as an anchor variable, there is no requirement to provision a calculated value for this and this error can be safely ignored. Red herring people!
Error #4: “You are not allowed to update the Certifier log”
My last error involves an error in the Sync engine “Invalid-attribute-value” and this error appearing in the Domino log:
————————————————————————————————————————
2013-07-17T13:57:53 [1156:3512] Trace – DominoPerson:RegisterUser : “Domino” – userIdFile : pearnm.id
2013-07-17T13:57:53 [1156:3512] Trace – DominoPerson:RegisterUser : “Domino” – MailServer :
2013-07-17T13:57:54 [1156:3512] Error – Person:ExportEntry : “Domino” – Exception Occurred
——— Outer Exception Data ———
Message: Notes error: You are not allowed to update the certifier log (Pearn)
Exception root Exception type: System.Runtime.InteropServices.COMException
Source: NotesRegistration
————————————————————————————————————————
This error essentially means the export .ID file that you’re using does not have rights to create ID files. Ask your Domino administrator to add your account to the ‘local domain admins’ group for that Domino Organisation. After my account was added to the correct Domino permissions, the export went through perfectly.