It's been ages since I've written on my own blog and thought I'd share one of the funkier projects I've done recently.
Connect ApacheDS LDAP directory to a SharePoint 2013 server.
Simple, you might think. SharePoint supports LDAP. Doesn't it?
Well, there are two ways you can achieve this. Either by directly connecting the apache directory server to SharePoint or through ADFS. This will be a two post blog and in my first post I'll cover the simple, direct connection approach.
For SharePoint to understand LDAP users you need following ingredients
1) Claims Based Web Application. Luckily in SharePoint 2013, that's the default
2) LDAP Membership Provider & LDAP Role Provider
3) People Picker Magic
4) LDAP Provider that can provide the UPN in a way that SharePoint can handle it.
Luckily Claims is the default setting on SharePoint 2010 and above. So you'll have no problems ensuring a claims driven scenario. The tricky part is chosing your Claims Provider. But Luckily the built in LDAP provided by MS actually works! Just sadly, all documentation out there on using it assumes that you're connecting your Active Directory Domain as LDAP source. Why anybody would want to do that instead of just using the native windows integrated mode has always been a mystery to me. But we can use that provider to hook up our ApacheDS LDAP source. All you need to do is know your LDAP details. Here is a good technet article on configuring the LDAP web.config settings
<membership>The things to keep in mind with apacheds:
type="Microsoft.Office.Server.Security.LdapMembershipProvider, Microsoft.Office.Server, Version=22.214.171.124, Culture=neutral, PublicKeyToken=71e9bce111e9429c"
connectionPassword="[email protected]" />
<roleManager enabled="true" >
type="Microsoft.Office.Server.Security.LdapRoleProvider, Microsoft.Office.Server, Version=126.96.36.199, Culture=neutral, PublicKeyToken=71e9bce111e9429c"
- Port is often 10389 instead of 389. so double check what port you're using, and pick the SSL/non SSL one respectively. (remember to set useSSL to true if you're going to)
- If you're going to go down the SSL path, make sure that the SharePoint server trusts the certificate.
- open mmc on the SharePoint server
- Import the SSL cert used to secure the LDAP server into the trusted root authority for the local computer
- update your user and group containers respectively. (careful when testing with the built in admin account. that often sits in a different container alltogether and it's best you create a test account in your main OU)
- apacheDS expects the fully qualified DN for login purposes. so you need to fully qualify your connectionUsername when polling the LDAP repository
- Careful with those fully qualified user names. A cn can be very different to a uid!!! Look at the DN(distinguished Name) of your user account carefully. best try to copy it in its entirety.
- big Gatcha: apacheDS will send back the DN of the account it finds that matches. That's the fully qualified distinguished name. So when you go and give a user access you'll need to be able to check the return value against their DN. sadly the DN is not a queryable attribute by default. To make it queryable, you need to add the distinguishedName to your LDAP Schema. you can find it by adding the extensibleObject class to your user schema. once you have the ability to add the distinguishedName atttribute to your users, and have set it to point at itself, the DN that the authentication module returns will match the distinguishedName attribute and voilla, the user will be let in.
- userName is often uid on an apacheds server, don't go looking for samAccountName
- group membership is often through the uniqueMember attribute on the group schema.
- Don't forget to configure your SecurityTokenServiceApplication!!! easily missed step
- Tip: don't just kill the clear tag which is killing the previous providers. That will come back to haunt you. do it properly and add the providers to the STSApp web config.
- Once you have ensured that it's all working, why not encrypt the web.config settings... you know, having plain text passwords in config files and that jazz. http://msdn.microsoft.com/en-us/library/vstudio/dtkwfdky(v=vs.100).aspx
- Just follow the above tutorial and replace connectionStrings with system.web/membership/providers (encrypting any part of the config file is easy once you understand that you need to treat it like xpath)
- do it again for system.web/roleManager/providers
- Oh, and you will want to add your LdapMember and LdapRole providers to your people picker. At least that's super simple. Just add to your peoplepickerwildcards section in the web config
some good resources on general SharePoint LDAP config using Forms Based Authentication (FBA) can be found here:
That's it! After you've spent many hours understanding the LDAP schema from apacheDS, tearing your hair out over distinguishedNames and got it all working for users to log in to SharePoint using their LDAP credentials you'll then be glad to know that FBA and Office Integration still sucks, even in 2013. The cookie that is used for the claim information can not be shared with the WebClient service which means that office and Explorer will ask for your credentials...again! Logging into different web applications (using different urls and thus cookies) will ask for credentials again! and best of all, if you followed the best practice recommendation from MS on how to setup your app framework, then you'll be hosting all your lovely apps on a completely different url and guess what, another login prompt again...
Now isn't that nice. But how can we provide a seamless single sign on experience to SharePoint for our LDAP users then? well FBA is not the way. but ADFS is! with ADFS you can configure all your webapps to use the same tokensigningauthority with the same realm and same claims. with ADFS tokens even explorer won't bug you for another login once you've logged into the website. A true single sign on experience!
But guess what. ADFS does not provide you with a way to authenticate users against anything other than Active Directory, you will need to add a ClaimProvider to your setup that can handle your LDAP login and create claims full of your lovely LDAP properties. But how? the answer lies in shibboleth.
So in Part 2 of this series I'll uncover the tricks required to get apacheds to talk to SharePoint using ADFS and shibboleth as the middle-men in the setup.
But before I go to the really cool ADFS bits, here some trouble shooting tips for the ldap connection
- Bump up your logging on the ldap server. Look for a log4j.properties file and change the logging level from WARN to DEBUG http://directory.apache.org/apacheds/basic-ug/1.4.4-configure-logging.html
- After changing the logging, reset your apache service on the ldap server. if it fails to start again, then DEBUG was too much for it to handle. try setting an individual category instead of the root category to DEBUG.
- Always remember to reset the service or the new logging settings won't take effect
- install netmon and fiddler on all your machines to trace the handshakes going on.
- Bump up your SharePoint trace log (found in Central Admin under Monitoring/Diagnostics)
- If the people picker works but sign in fails, double check your web.config for the STSApp. Often missed, especially when troubleshooting and not updating that one with the latest changes
- if you can't get the people picker to show users in Central Admin, remember to add the providers and peoplepicker settings to the web.config of CA as well!
- to save some pain consider updating the machine.config for the whole server. (plus the STSApp, which needs special treatment due to a very annoying clear directive
- Not all sections of the web config like being encrypted. You will need to be very specific about the section you encrypt. Don't try to go too broad.