We recently migrated our internal Knowledge Base to Confluence. Part of the process involved linking Confluence to Active Directory... one directory to rule them all... one directory to bind them... Anyway. Doing the basic connectivity part is easy - simply following the prompts should successfully link your new Confluence instance to AD, BUT what you'll find is that you return too many users, which with Confluence can have a relatively disproproportionate cost impact. The Confluence examples don't work, and neither does the MS doco.
You won't experience this issue if:
- You have all of your users in a single OU
- Move disabled users to a different OU
- Don't have any system accounts or user templates in the same OU
but if you do (for example SBS will have several of these) then you're in trouble, and your (low) number of users might rapidly look like 30 or 40 users. Ouch!
First, an example of how you both define the base DN and filter users by a couple of conditions, then a bit more of an explanation and some tools to help you troubleshoot.
Your base DN will look something like: DC=mydomain,DC=com
Additional User DN: ou=SBSUsers,ou=users,ou=MyBusiness
(This is how you map the SBS User container to LDAP)
And under User Schema Settings:
User Object Filter: (&(memberOf=CN=myADConfluenceGroup,OU=Security Groups,OU=MyBusiness,DC=mydomain,DC=com)(userAccountControl=512))
This last one does two things - it looks for Enabled users (userAccountControl=512) and it filters by the Active Directory Group "myADConfluenceGroup". So the net effect is:
- Confluence looks in the SBS User Container for enabled users that belong to the myADConfluenceGroup, and only returns these. Voila!
A few notes on the above:
- The actual syntax for an LDAP query isn't straight forward, so you're probably better off using a tool to help you build your query and test it first. Some tools that I used:
- LDP - The inbuilt Microsoft LDAP query tool. You can use this to execute a query to test it, but the interface is a bit sparse.
- MS Doco on LDAP search filter syntax http://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx
- LDAP Admin Tool from LDAPsoft http://www.ldapsoft.com/ . The standard tool will work fine and was a good help in troubleshooting and building the correct query. The search building interface and failure to remember the correct base DN for queries is painful however, and the lack of a history feature (i.e. showing you what queries you've executed in a log, ala MySQL Workbench) makes it unnecessarily more difficult. Lastly when you tweak a previously successful query it overwrites the old one, so you lose the history of the query that worked. But all in all it was a useful tool that helped me get the results I needed.
- JXplorer - it simply crashed when starting with a class version error. This is the tool that Confluence recommends for troubleshooting, but after cruising the JXplorer forums to try and resolve the JXplorer bug I switched and went for a different tool instead. Disappointing.
- Some of the Confluence doco... http://confluence.atlassian.com/display/DEV/How+to+write+LDAP+search+filters (helpful) http://confluence.atlassian.com/plugins/viewsource/viewpagesrc.action?pageId=280692518 (not as helpful)
- Some other doco out there: http://docs.jivesoftware.com/jive_sbs/3.0.13/admin/LDAPActiveDirectoryGuide.html has some good examples including some very close to the example above. The examples on the page won't work against SBS / Confluence.
There were two real gotchas in all this. The first was the syntax to correctly join multiple criteria, and the second was correctly referencing the objects.
The Confluence doco (reference above) has some good notes on the join syntax. But... in your join you will need to correctly reference the desired object.
Note in this line: memberOf=CN=myADConfluenceGroup,OU=Security Groups,OU=MyBusiness,DC=mydomain,DC=com
That we're referencing the entire LDAP location from start to finish - the base is not usedin the filter, so we have to specify the whole lot. And remember that what will happen here is that it will filter the previously retrieved list of users, looking for ones that have "CN=myADConfluenceGroup..." in the "memberOf" attribute.
And the third was working out how to identify a disabled user in AD. The attribute you need is "userAccountControl". I've only looked in our own directory, so I can't confirm if the values of 512/514 are specific to our installation, or generically true (if someone can confirm this please let me know). To confirm, find an active user, look for this attribute and it's value, then a disabled user and compare.
Lastly... I found trying to use an AD group with the same name as the Confluence groups didn't work - it had erratic results. For example I could see the group in Confluence, but it contained no users. I could walk through the add user to group workflow, but when you go to view the actual group there's nobody actually added. In the end I just created a new group in AD for Confluence. Initially I was going to use the Sharepoint group BUT again there are some users who I didn't want in there (such as domain admin).