Monday, February 27, 2012

Deploying a Mediawiki server in an Active Directory environment

I recently implemented a knowledge base web application at work using Mediawiki.  There are a number of group collaboration packages out there, but I was really looking for something that would be extremely simple.  I wanted to create a knowledge base web site to replace a  bunch of folders full of Word documents shared on our servers.  Since all of this information is meant to be shared with anybody in the company my aim was to provide something that would make it easier for people to find information or at least make it easier for them to remember where to look.  I prefer to follow Unix philosophy whenever possible even though I am currently working in a predominantly Windows environment.  Part of that philosophy is keeping things as simple as possible and making each component in a system do one thing well.  With that in mind I didn't want to implement a complicated groupware system that had a bunch of features that would either confuse people or just not get used.  For this project I didn't need a document management system, enterprise social networking, project management, granular permission sets, etc.  I just wasn't looking for a one web application to rule them all sort of a setup.    My other criteria when choosing a software package was that the organization behind it have a good history, that they provide regular updates, that there is a good likelihood that the software will have a future, that there is good documentation for it and that data could be migrated to another platform in the future if necessary.  Basically it needed to be easy to install and maintain either by me or anyone else that needs to maintain it in the future and our data should not be locked into a proprietary format.  Mediawiki fit all of those requirements and it does the one thing that it was designed for well.

I expect that the majority of our users will be content consumers rather than contributors, so I was not terribly concerned with authenticating everyone.  If all somebody needs to do is read something I didn't want to force them to log into the site.  I did however want some amount of accountability for the edits that are made to the pages in the knowledge base so it needed to have a user authentication system to log users in before editing content.  If you are implementing any sort of application that uses authentication, you'll can make both using your application and administering it much easier by using a centralized authentication mechanism.  So my one requirement in this regard was that the system must allow them to use their existing Active Directory user account to log in.  Using Ryan Lane's "LdapAuthentication" extension made things easier for me and our users.

The installation instructions for this extension are well documented so I won't go into great detail here. Basically you need to install the required software packages on your system and install the certificate(s) of the domain controller(s) and configure open-ldap telling it where you have stored those certificates.  Next you'll need to create a user with read access to Active Directory to act as a proxy for your application.  A regular user with no special privileges will work just fine.  My proxy user is just a member of the "Domain Users" group and that's it.  Download the latest tarball of the extension and extract the contents into its own directory underneath your extensions directory and you're ready to configure it.

I found some of the documentation of the configuration to be somewhat incomplete but appropriately the documentation was hosted on a Mediawiki site, so I created a user account and made some edits to add what I found to be lacking.  Here is the configuration that is in my "LocalSettings.php" file.

# End of automatically generated settings.
# Add more configuration options below.

#LdapAuthentication Configuration

$wgAuth = new LdapAuthenticationPlugin();
$wgLDAPDomainNames = array("domain");
$wgLDAPServerNames = array("domain" => "domainController.domain.local");
$wgLDAPSearchStrings = array("domain" =>"domain\\USER-NAME");
$wgLDAPSearchAttributes = array("domain" => "sAMAccountName");
$wgLDAPBaseDNs = array("domain" => "dc=domain,dc=local");
$wgLDAPEncryptionType = array("domain" => "ssl");
$wgMinimalPasswordLength = 1;
$wgLDAPDisableAutoCreate = array("domain"=>false);
$wgLDAPProxyAgent =  array("domain" => "cn=proxyUser,ou=organizationalUnit,dc=domain,dc=local");
$wgLDAPProxyAgentPassword = array("domain"=>"V+r<I(DNm8%vA");

Some explanation of these lines are in order to fully understand what you'll need to fill in for your particular environment.   I'll now go over the configuration.

$wgAuth = new LdapAuthenticationPlugin();

These two lines tell your Mediawiki installation to load the extension and create a new instance of the LdapAuthenticationPlugin class to use as its authentication mechanism.  Please take care to ensure that "$IP/extensions/..." is the actual path into which you unpacked your extension.

Anywhere that you see "domain" in my example, just substitute the NETBIOS domain name for your AD domain.  The $wgLDAPServerNames array is a space separated list of your domain controllers that you'd like your server to talk to.  $wgLDAPDomainNames, $wgLDAPSearchStrings and $wgLDAPSearchAttributes are self-documenting.  

Your $wgLDAPBaseDNs variable is where you would like the extension to start searching for users.  In the example above it would start at the domain root, but you can start at any arbitrary container as long as all of your users accounts will be found below there in the AD structure, e.g. cn=users,dc=domain,dc=local or ou=users,ou=northamerica,dc=domain,dc=local.  

Using "ssl" for $wgLDAPEncryptionType will keep your domain credentials secure from eavesdropping while they are sent over the wire.  

Setting $wgMinimalPasswordLength to "1" just means that you can't have a blank password.  

The variable $wgLDAPDisableAutoCreate should be set to false if you would like to have Mediawiki automatically create new Mediawiki user accounts for any users that it finds in Active Directory.  If you comment out or delete this line, the default will be false however explicitly setting it makes for good documentation of what your intention is.

Your $wgLDAPProxyAgent will be the full LDAP distinguished name of your proxy user account and $wgLDAPProxyAgentPassword should be a randomly generated complex password such as the example above.

Running a Mediawiki server makes for an easy way for people to share information in a format that they are comfortable using.  Running it with the LDAP Authentication extension installed introduces a modicum of accountability for those that choose to edit or post content with the ease of using account credentials that they already have.

No comments:

Post a Comment