SharePoint Server 2010 User Profile Synchronization with Novell eDirectory 8.8 SP6

Print | posted on Monday, February 21, 2011 10:08 PM

Introduction

It’s been brought to my attention recently that you all love the User Profile Synchronization service instance in SharePoint Server 2010! :). So much so in fact, that one of the most common requests I get is for more articles on this topic, and in particular details on syncing with directory systems other than Active Directory.

There is very little documentation about syncing with Novell eDirectory. Basically none. Unfortunately at present TechNet only provides cursory information regarding permissions, and the early White Paper is extremely weak in this regard. Neither provide the necessary details to get it running.

This article will walk through the steps necessary to get everything working. Be aware, there’s some nastiness involved (this time on both ends of the sync connection), so make sure you are ready before you start!

I will take my usual approach and explain things as I go, there are a number of key gotchas and “interesting” configuration. I will also perform tasks which are not necessary to show the “why”. Therefore the steps below are not the optimum steps that you would use to configure things for a production deployment. This article is for educational purposes, it’s not supposed to be a cheat sheet for your consulting engagements! :).

What on earth is Novell eDirectory?

It’s NDS rebranded about the same time as having a little ‘e’ in product names was “cool”, before ‘i’ became “cool”. That’s a bit harsh actually, but it’s definitely a 1990s technology. It sucks, I don’t mind saying it. I’ve been doing “Identity Management” for a (way too) long time, and this particular product has always given me the shivers. But lets not forget, NDS was around long before Microsoft got with the program and implemented an LDAP directory service. Thus, there’s a lot of it still about, and Novell now has a comprehensive suite of tooling in the identity management space (just like Microsoft does). Many corporations rely on the Novell stack and there are still many who consider a non-Microsoft directory service more appropriate for things like extranet authentication.

Whilst SunOne appears to be the most commonly implemented non-AD directory service with SharePoint 2010, there are plenty of valid requirements for using eDirectory for user attributes in the SharePoint-verse.

In terms of setting it up, you will be much better off if you know eDirectory. I know this sounds like an obvious statement, but the reality is that SharePoint people are generally not directory services experts. Ideally you will have a buddy who can help you with the eDirectory side of things. If not, there’s nothing too difficult involved and if you are working in a lab, the steps here are fairly straightforward.

Preparing the Platform

Before we can get started we need a base platform. This article uses a very simple environment which consists of:

1. CONDC1: An Active Directory Domain Controller for the domain, contoso.com.
2. CONSQL1: SQL Server 2008 R2 & Novell eDirectory 8.8 SP6 for the tree, contoso.
3. CONSP1: SharePoint Server 2010 (December 2010 CU)

All servers are running Windows Server 2008 R2 Service Pack 1. I also have the Novell iManager web based administration tool with the eDirectory and Certificate Server plugins installed on CONSQL1. This is the minimum you need to follow the article. You may choose to use ConsoleOne instead of iManager. You will also need an LDAP tool of your choice to make changes to attributes. I use LDAP Admin Tool from LDAP Soft.

A SharePoint Farm has been created and the necessary services configured. I assume you are comfortable with this. Importantly, the User Profile Service Application has been created and it’s associated service instances have already been started. Please head over to my Rational Guide for the details on how to do this. If you haven’t got UPS up and running yet, there is no point reading any further.

In addition there is an eDirectory tree, named contoso, already configured. I am not going to walk through the steps to install and configure eDirectory. I will detail the steps required in eDirectory to configure Profile Synchronization only. The eDirectory installation was performed with the default settings on purpose to demonstrate certain issue-ettes.

Planning is Paramount

Yes, you need to plan! It’s probably the most important part of any UPS deployment aside from patience!

Chances are you are not in control of eDirectory just like you are not in control of Active Directory. There are a number of configuration changes required in eDirectory to get things working and you must gather the appropriate information upfront and start a conversation with the DS admins. If you don’t do this you will fail, guaranteed.

Here’s an example. If you take a look over at the excellent Plan for profile synchronization on TechNet, you will note that UPS supports Novell eDirectory 8.7.3. Hmm, but we are running 8.8.6. This will require both changes to FIM (which is notoriously finiky about versions) and eDirectory. If we don’t have that planed out, when we attempt to create a sync connection it will blow up in our faces. Of course the IDM practice discipline of planning out property mappings and so on remains just as valid as well.

But what about vendor supportability?
There couldn’t be a more ambiguous statement than “The directory services supported in SharePoint Server 2010 and their synchronization capabilities include the following” (from the Plan article on TechNet).  It’s like this: the versions listed are those which were tested for the RTM of SharePoint 2010.

We don’t want to be running 8.7.3. I don’t think that one is even available on x64 Windows, regardless it’s old and crappy. I can guarantee you a 100% stone cold fact: eDirectory 8.8 is supported with FIM 2010. In addition, the changes we need to make are very similar to those documented for SunOne.

Preparing for User Profile Synchronization

Before we can go ahead and start configuring things in SharePoint, we need details of and potential changes made to eDirectory. Make sure you have or can gather all of the below before starting.

1. Create a user in eDirectory, this will be the account used by our Synchronization Connection.
   Do not use the eDirectory admin account! The good news is that this account doesn’t need any “special” rights on eDirectory (like the AD Sync account needs Replicating Directory Changes).
   
   All the account needs are Browse and Read on the objects you are syncing with, and Compare rights in the All attributes rights property for the specified tree. If you want to do export to eDirectory, you also need Write on the objects you are syncing with.
   
   That’s actually quite a lot, and you will likely need to have that conversation with your eDirectory admin. Without those rights, it will not work. It’s that simple.
2. Export the Signing (Issuer) Certificate from eDirectory.
   By default, eDirectory creates self-signed certs. As we will be doing SSL connections to eDirectory, we need to be able to install the Issuer certificate into the Trusted Root Certificates store on the machine running FIM. In a real world deployment the eDirectory should be using a Trusted Certificate Authority and this is a non issue. More on SSL issues towards the end of this article.
3. Gather information about eDirectory.
   We must have certain information about the eDirectory in order to configure profile sync. The details we require are:
   • The value of the vendorVersion attribute of the RootDSE object.
   • The server name and IP address of the machine we will connect to and sync with.
   • The value of the nonStdClientSchemaCompatMode attribute of the server object (the server we will connect to).
   • The value of the ldapSSLPort attribute of the server object.
   • The value of the ldapTLSRequired attribute of the server object.
   • The value of the ldapAllowClearTextPassword attribute of the LDAP Group object
   • The Organizational Units where users we wish to sync with are stored. I will use one called SharePoint Users for this example scenario.
   We need all of the above, otherwise we will not be able to configure things without a lot of hassle. The last one, of course is a key planning aspect. It is likely that the OU design has not been created for SharePoint, and you will need to plan your connections and filters around what is in place.
4. Make or Request required changes to the eDirectory server.
   If nonStdClientSchemaCompatMode is FALSE, profile sync will not work. This is a requirement for the FIM eDirectory Management Agent. This must be changed on the server to TRUE. If there is concern about this, another eDirectory server dedicated to UPS can be deployed. There is zero security risk in changing this value. It effectively allows the server to return “legacy” responses to requests for the schema which don’t include newer features of the DS. Think of this as an analog to functional levels in Active Directory.
   
   If we don’t do this we will receive the dreaded, unable to process create message error when we try to save our sync connection. This is a generic error, regardless of the root cause. The underlying error returned by FIM here is “unable to retrieve schema”.
   
   Connect to eDirectory using the LDAP tool of your choice, and select the cn=LDAP Server object of the server you are syncing with. Edit the nonStdClientSchemaCompatMode attribute to TRUE.
   
   
   
   Restart the LDAP Server on this machine for the change to take effect.

Configuring the SharePoint Central Administration web.config

OK, now we have our eDirectory ready we can start to configure the SharePoint side of things.

In order to create our sync connection we need to add a membership provider element to the web.config of Central Administration. It is not required to add the same to a content web application or the STS web.configs. In a real scenario, we will do that of course, so that users can authenticate against eDirectory. However for profile sync alone, we just need one in the CA web.config.

This is in order to populate the Authentication Provider drop down on the Add new synchronization connection page. As we will see a little later, we must have the dropdown populated otherwise things won’t work. We don’t need to include all the details here that we would normally use for an authentication scenario. For example we can just have the following entry:

<membership>
    <providers>
        <add name="eDirMember" type="Microsoft.Office.Server.Security.LdapMembershipProvider,Microsoft.Office.Server, 
Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"     
/>
    </providers>
</membership>

And we will be able to create a sync connection just fine. Don’t forget the details we enter in the Add new synchronization connection page are saved as properties of the Management Agent inside FIM. Once we are doing sync we don’t care a jot about the web.config. Besides, we are NOT doing Forms Authentication anyway, we are in this case doing Simple LDAP Authentication – which means username and password in clear text.

That’s quite nice because it doesn’t contain any credentials. In fact it could be the SQL provider all we need is a name to show up in the dropdown. Of course in the real world, we would need to include other details required for user authentication so we could use the people picker and so on, and we’d need the same entry in our STS and content web application’s web.config.

<add name="eDirMember" type="Microsoft.Office.Server.Security.LdapMembershipProvider, Microsoft.Office.Server, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" 
     server="10.10.10.101"
     port="636" 
     useSSL="true" 

     connectionUsername="cn=spups,o=CONTOSO"
     connectionPassword="password"

     useDNAttribute="false"
     userDNAttribute="entryDN" 
     userNameAttribute="uid" 
     userContainer="ou=SharePoint Users,o=CONTOSO" 
     userObjectClass="Inetorgperson" 
     userFilter="(ObjectClass=*)" 
     scope="Subtree" 
     otherRequiredUserAttributes="sn,givenname,cn"
/>

I strongly recommend you get into the practice of using the complete entry. There are scenarios where you just want profile sync, but they are rare. In addition, it is likely the behaviour of the Add new synchronization connection page will change in a future CU. 

Note the format of the server – I am using an IP Address, and I strongly recommend you do the same to avoid certificate name validation problems when creating connections using default certs with eDirectory. These problems also bubble up the unable to process create message error! FIM will report “the server is down”. The System Event Log or Network Monitor will tell you the actual issue at hand here.

The port is that which we collected earlier from the ldapSSLPort attribute. We must also set useSSL to true to do a secure bind.

Also note the format of the username. this is important. it must be a fully qualified name in the format that eDirectory expects. Of course we have a plain text password there as well, another good reason for not using the admin account!

Of course the other attributes will vary based upon your scenario.

Importing eDirectory Certificates

If we are using the default eDirectory CA, we must import the Issuer certificate used by eDirectory to the Local Machine Trusted Root Certificate Authority store on the machine which will run the UPS service instance. We cannot import this cert to the FIM Sync service account store, as it is self signed.

In a real world deployment we wouldn’t (we hope) be using self signed certs. However SSL issues are the number one cause of problems connecting FIM to eDirectory (or any LDAP service). The FIM Sync service account must have the correct certs. Bear this in mind if your eDirectory is using a enterprise CA that the SharePoint machine is not participating in.

Use the Certificates.msc plugin to import the Issuer Certificate (default name Organizational CA) into the Local Machine Trusted Root Certificate Authority store:

That certificate is now available machine wide.

Configuring the eDirectoryMASupportedServers Registry Key

If at this point we attempt to create a Sync Connection, we will again be able to populate containers, but we won’t be able to save our Sync Connection. If you remember from above, the minimum version supported is 8.7.3. The error again will be unable to process create message. What else? :). Here you can see the underlying error in FIM:

In order to be able to save a Sync Connection for a version of eDirectory greater than 8.7 we must create a registry key at the following location:

HKLM\SYSTEM\CurrentControlSet\Services\FIMSynchronizationService\Parameters

Value Type: Multi-string Value (REG_MULTI_SZ)

Value Name: eDirectoryMASupportedServers

Value: LDAP Agent for Novell eDirectory 8.8 SP6 (20601.08)

The value is the exact string in the vendorVersion attribute of the RootDSE object collected earlier. Yours may be different, and multiple entries are allowed.

This is 100% supported by FIM 2010. There is also a similar approach needed for SunOne, for which there is an existing SharePoint specific KB article.

Once this is done, in combination with the nonStdClientSchemaCompatMode attribute in eDirectory we can finally create a sync connection!

Creating a Synchronization Connection to eDirectory

There’s no two ways about it, the Add new synchronization connection page is terrible. Let’s walk though the skinny.

We’ll go ahead and populate the form using the default approach. We enter a Connection Name and then select Novell eDirectory from the Type combo box. This refreshes the page, and note that the Authentication Provider Instance combo box is now disabled and a Provider Name text box appears at the bottom.

So far so good. Let’s hit Populate Containers, and that works as well, and we can select our OU(s):

Great! But the problem comes when we hit OK to save the connection. It will fail to even pass the page validation, and we will get the following warning:

This is a huge BUG! and it’s undocumented. What we’ve tried to do so far seems reasonable right? We’ve followed the UI as it attempts to guide us through. But it will never work! It’s barfing on the user name validation. This is the problem with using generic modal forms for things of significantly different natures.

Don’t be confused by the labels, the user name must be in the fully qualified format, e.g.
CN=spups,o=contoso. But this page doesn’t understand that, or reflect it.

We need to trick the page into giving us back the Authentication Provider Instance combo box.

We need to start over by clicking the Create New Connection button on the Synchronization Connections page. Make life easy by going out and back in – this page can get mighty confused! Enter a Connection Name and once again select Novell eDirectory from the Type combo box. Notice that the Authentication Provider Type combo is Forms Authentication and the one we want to use is disabled again.

Here’s the trick. Select Trusted Claims Provider Authentication in the Authentication Provider Type Combo. The page will refresh:

And then, in the same combo box, select Forms Authentication. The page will refresh again.

Notice how now the Authentication Provider Instance is now enabled and has our entry available!!! Also the Provider name text box is nowhere in sight! Don’t ask, if I knew I couldn’t tell you!

This is basically how we can trick the page into giving us the right form which will pass validation. Let’s go ahead and complete the details.

Hit Populate Containers and select our OU(s).

Now when we hit OK, the page will pass the validation and an attempt to save the Sync Connection will be made.

If you’ve done everything correctly, the sync connection will be saved!

If at this point you get the dreaded unable to process create message error, that means you have done something wrong. The most common causes are:

1. Not importing the Issuer cert
2. Not creating the eDirectoryMASupportedServers registry key
3. Not enabling nonStdClientSchemaCompatMode on eDirectory
4. SSL Validation issues, don’t use server names with eDirectory self signed certs or even if you create another one with Subject Alternative Names. It will not work.

So there we go. A nice “little” gotcha when creating sync connections!

Performing the first Full Synchronization

At this stage we can go ahead and create any Connection Filters and Property Mappings we may need as normal. But remember at this stage we have only saved a connection and set some properties. We still have to actually perform a sync. Assuming we have the necessary permissions on the sync account, once we run a full sync we will get our profiles imported.

You may also note that in various places, TechNet says that Incremental Sync with eDirectory is not supported. That’s a simple mistake which will hopefully be corrected soon. Incremental Sync with eDirectory is possible and supported. Incremental Sync is supported for every source! It would be totally unworkable to have to run a full sync (which cannot be scheduled) and that’s not how FIM is designed or works.

Note that when working with eDirectory you will have to do a bunch of work with Property Mappings. The defaults are designed for Active Directory and therefore many of the attributes are different and the mappings don’t make sense. Once again, this part is all about planning.

What about doing sync over non SSL LDAP?

You shouldn’t be doing it. It’s a simple as that! You do not want to be passing credentials over the wire in plain text, and you don’t want to be passing PII over the wire in the clear either. It’s a bad idea. I’ve shown how to do it properly, and you should really be doing this. Sometimes however, the eDirectory administrator has disabled secure binds to support legacy applications. If you cannot use SSL, then on teh SharePoint side it’s a question of using port 389 and unchecking the useSSL option on your Sync Connection.

If you want to open up eDirectory to use regular LDAP, that is a question of configuring the following attributes and restarting the LDAP service:

• The value of the ldapTLSRequired attribute of the server object.
• The value of the ldapAllowClearTextPassword attribute of the LDAP Group object

This is for information only, you should not be doing profile sync over non SSL connections! If you want to do this because certificates are causing you problems, it is not an appropriate solution. Resolve the cert issues!

Summary

It’s actually pretty straightforward. Despite a few roadblocks and the comedy of the New Synchronization Connection page. The real issue here has been the lack of documentation. Now you have all the information you need to get this set up. Of course, I’ve showed a number of things to explain the issues, you wouldn’t follow the steps to deploy into production. In summary, the ideal order is:

1. Export Certs and detail eDirectory configuration
2. Modify eDirectory to allow legacy schema retrieval
3. Import Certs on machine running the UPS service instance
4. Create Registry Key on machine running UPS service instance
5. Add the Membership Provider to the CA web.config
6. Use the “trick” to create the sync connection

I hope this article is useful, please feel free to drop me comments about what other UPS related topics you’d like to see covered in the future.

.