Integrating MediaWiki with LDAP

Use ApacheDS to test and configure LDAP authentication with MediaWiki

Learn how to add a Lightweight Directory Access Protocol (LDAP) authentication module to MediaWiki that will allow it to authenticate users against an LDAP directory. Gain a better understanding of MediaWiki, Apache Directory Services (ApacheDS), and Apache Directory Studio, and how you can use them to create an LDAP directory for testing.

Share:

Nathan A. Good, Web Developer, Freelance Developer

Nathan GoodNathan A. Good lives in the Twin Cities area of Minnesota. Professionally, he does software development, software architecture, and systems administration. When he's not writing software, he enjoys building PCs and servers, reading about and working with new technologies, and trying to get his friends to make the move to open source software. He's written and co-written many books and articles, including Professional Red Hat Enterprise Linux 3, Regular Expression Recipes: A Problem-Solution Approach, and Foundations of PEAR: Rapid PHP Development.



07 February 2012

Also available in Chinese Russian Japanese Portuguese

Before you begin

In this article, you learn about binding MediaWiki with LDAP for authentication. Using LDAP for authentication enables you to simplify user management so you don't have to maintain users and permissions in two or more different places. Because many PHP solutions have LDAP authentication support available, LDAP may be your choice to create a central user and group repository.

Before you begin, you need the following:

  • PHP 5.1 or higher (Consult MediaWiki's site for details about required PHP versions.)
  • MySQL 4.0 or higher or PostgreSQL 8.1 or higher
  • The PHP LDAP authentication module

See Resources for links.


MediaWiki

MediaWiki is a solution implemented in PHP that provides wiki functionality—the ability for any user with the correct permissions to edit the contents of a web page. There are many examples of MediaWiki in action—the most famous may be Wikipedia, which serves millions of users worldwide (see Resources).

You can download MediaWiki free (see Resources). The download includes a high-level overview about installing MediaWiki on your system.


ApacheDS

ApacheDS is an LDAP implementation written in the Java™ language. Its cross-platform nature makes it a good solution for testing and using on almost any platform.

LDAP is an application protocol that specifies a method for accessing and storing directory information. Usually, this directory information is in the form of user information, such as names, user names, and groups to which the users belong. You can use LDAP implementations for anything from enterprise e-mail address directories to authentication and authorization.

In addition to using ApacheDS for services, you can install the Apache Directory Studio to help you administer the directory services. It is a plug-in for Eclipse that provides a graphical user interface (GUI) to easily browse an LDAP tree and view and edit users and groups.


Install ApacheDS

There are two ways to install ApacheDS for testing the authentication with MediaWiki:

  • Install the Apache Directory Studio plug-in to the Eclipse integrated development environment (IDE).
  • Install the ApacheDS server only.

Install the Apache Directory Studio plug-in to the Eclipse IDE

When you install the Apache Directory Studio plug-in, it installs an embedded version of the ApacheDS server that you can run and use. For following along in this article, this solution is ideal because you can get the solution up and running quickly.

To install Apache Directory Studio, open the Eclipse IDE, select Help > Install New Software, and enter the Apache Directory Services update site URL (http://directory.apache.org/studio/update/1.x). Make sure you select all the features (see Figure 1), and then click Next to install them.

Figure 1. Install the Apache Directory Studio features in Eclipse
Installing the Apache Directory Studio features in Eclipse

If you agree to the terms and conditions, accept them and continue. You need to restart Eclipse for the changes to take effect.

After you restart Eclipse, switch to the LDAP perspective by selecting the Window > Open Perspective menu option.

To create a new server instance, click on the Server tab and click the Add button. Name the new server local, and then click Finish when you're done. You can start the server by clicking Run from the context menu.

You need to create a connection to the server before you can browse its LDAP directory with the LDAP browser. To create the connection to the server, click on the server on the Servers tab and select LDAP Browser > Create Connection. The plug-in creates a new connection in the Connections tab.

Install the ApacheDS server only

To install the ApacheDS server only, download the appropriate binary for your operating system from the ApacheDS download site (see Resources).

If you use the binary archived version, extract it to a folder after you download it. After you extract the files into the folder, you need to set up an example partition to start the ApacheDS services (see Resources). If you don't set up the example partition, you will get errors when you try to start the services.

When you have it extracted, you can run the apacheds.bat file if you are using Microsoft® Windows®. Run the apacheds.sh shell script if you are using Mac OS® X or Linux®.

To connect to the server that you just created, use LDAP Browser > Create Connection. You will see the new connection in the Connections tab. You will also see the connection details in the LDAP Browser tab.


Set up users and groups

Before continuing to get MediaWiki running, you should set up some users and groups to test the authentication. If you want to simply import some sample users and groups, you can import the LDAP Data Interchange Format (LDIF) file included with this article (see Download).

If you're setting up a structure yourself, you should add a context entry by selecting New > Context Entry from the shortcut menu. This allows you to add the domain components and organization in which to add your users and groups.

Set up users

The easiest method of setting up a user using the LDAP browser is to clone an existing entry. The ApacheDS plug-in comes with one user, admin, already set up. The admin user's LDAP Distinguished Name (DN) is uid=admin,ou=system. The DN for a user or group is a fully qualified name that uniquely identifies the entity. The "Configuring authentication" section describes DNs in more depth.

Complete the following steps to clone the admin entry:

  1. Select LDAP > New Entry.
  2. Select Create entry from scratch as shown in Figure 2.

    Figure 2. Creating a new entry from scratch
    Creating a new entry from scratch
  3. Add the inetOrgPerson object class as shown in Figure 3, and then click Next.

    Figure 3. Adding the inetOrgPerson object class
    Adding the inetOrgPerson object classn
  4. Add a unique user name assigned to the uid as shown in Figure 4, and then click Next.

    Figure 4. Defining the uid field for the new user
    Defining the uid field for the new user
  5. Add the values for the cn and sn fields as shown in Figure 5, and then click Finish.

    Figure 5. Setting the values for the new user
    Setting the values for the new user

Now that you've created the user, you can find it in the LDAP browser as shown in Figure 6.

Figure 6. Viewing the new user in the LDAP browser
Viewing the new user in the LDAP browser

You can edit an LDAP entry by clicking on the entry in the list and then selecting Edit Entry from the context menu or pressing the F7 key. By editing the entries, you can change the name of the user (cn) and how the user's name is displayed (displayName). Make sure you change the user's password to something that you will remember later when you're testing the login from MediaWiki.

Set up groups

You can set up a group for your users by selecting New > Entry. In the Object Classes window, select the groupOfUniqueNames object class as shown in Figure 7.

Figure 7. Using the groupOfUniqueNames object class
Using the groupOfUniqueNames object class

Now follow the same steps you used when setting up the user, except define the cn field for the name of the group instead of using the uid field. You can add a user's DN in the value for the uniqueMember attribute. Figure 8 shows how the group displays in the LDAP browser when you're finished.

Figure 8. The group details as shown in the LDAP browser
The group details as shown in the LDAP browser

Now that you've set up users and groups, you're ready to configure MediaWiki and add the proper extension to authenticate against your LDAP directory.


Install MediaWiki

To install MediaWiki, download the archive file from the MediaWiki site (see Resources). The high-level steps for installing MediaWiki are:

  1. Extract the contents of the archive file into a folder available to your web server.
  2. In your browser, navigate to the config directory (for example, http://localhost/mediawiki/config/index.php).
  3. The MediaWiki installer will walk you through the rest of the steps.

To get more information about installing MediaWiki, see Resources for the full installation guide.


Install the MediaWiki LDAP module

When you have MediaWiki up and running, you need to install the MediaWiki LDAP module to bind to the ApacheDS instance and authenticate users.

To install the module, to go the MediaWiki's LDAP Authentication extension's site (see Resources) and download the snapshot. Extract the extension into the mediawiki/extensions folder so that your extension folder looks like Listing 1.

Listing 1. The contents of the MediaWiki extensions folder
mwuser@umediawiki161:/var/www/mediawiki/extensions$ ls
LdapAuthentication  README

Now that you have installed the extension into the correct folder, you are ready to modify the LocalSettings.php file to add the configuration values for the extension.


Configure authentication

Configuring the module to work against LDAP is arguably the most difficult part of the process. The names in LDAP can be confusing, so it's difficult to get them correct if you don't know what they mean.

In a directory, entries are given class designations in the objectClass field. It's important to remember that an entry can contain more than one instance of the same field, but with different values. Any entry can contain more than one objectClass field-value pair.

The classes describe which fields are required and allowed on the entry. A group, for instance, is simply an entry that contains the groupOfUniqueNames object class. Entries with this class can have one or more uniqueMember, which contains the DN of a member (user) for that group. Users, on the other hand, are usually entries of type inetOrgPerson for purposes of authentication.

In ApacheDS, you configure entries that contain the DNs for both users and groups. As mentioned earlier, the LDAP DN for a user or group is a fully qualified name that uniquely identifies the entity. The DN contains a comma-separated path of LDIF fields that start out specific in scope and fully qualify the object. If the DN represents a user, the DN can contain the common name (cn) or the user identifier (uid).

For example, given a user in your new ApacheDS directory, such as editor1, the DN might be uid=editor1,ou=users,o=wiki,dc=mywiki,dc=com. Table 1 contains more information about the fields in this DN.

Table 1. The fields that appear in a DN
FieldExampleDescription
uideditor1The unique identifier for the user name, usually the user's login name.
ouusersThe name of the organizational unit to which the user belongs.
owikiThe name of the organization.
dcdc=mywiki,dc=comThe domain component for the organization. This usually maps to the Internet domain name. For example, this dc entry might map to mywiki.com.

Groups are specified much like users, where the field that identifies the group uniquely might be the common name (cn) field instead of the uid. An example group DN is cn=wikiusers,ou=groups,o=wiki,dc=mywiki,dc=com.

See Resources for more information about LDIF.

With a basic understanding of the DNs in LDAP, knowing what to enter for the configuration becomes a bit easier. To add the configuration to MediaWiki, edit the LocalProperties.php file in the MediaWiki home directory and add the code shown in Listing 2.

Listing 2. The configuration code inside LocalSettings.php
require_once("$IP/extensions/LdapAuthentication/LdapAuthentication.php");

$wgAuth = new LdapAuthenticationPlugin();

$wgLDAPDomainNames = array("ApacheDS"); 
$wgLDAPServerNames = array("ApacheDS" => "ldap.example.com"); 
$wgLDAPPort = array("ApacheDS" => 10389); 
$wgLDAPEncryptionType = array( "ApacheDS" => "clear"); 

$wgLDAPProxyAgent = array( 
    "ApacheDS"=>"uid=proxyuser,ou=users,o=wiki,dc=mywiki,dc=com");
$wgLDAPProxyAgentPassword = array( "ApacheDS"=>"password"); 
$wgLDAPGroupUseRetrievedUsername = array("ApacheDS"=>true);
$wgLDAPSearchAttributes = array( "ApacheDS" => "uid");
$wgLDAPBaseDNs = array( "ApacheDS"=>"dc=mywiki,dc=com");
$wgLDAPGroupBaseDNs = array( "ApacheDS"=>"ou=groups,o=wiki,dc=mywiki,dc=com");
$wgLDAPUserBaseDNs = array( "ApacheDS"=>"ou=users,o=wiki,dc=mywiki,dc=com");

$wgLDAPGroupUseFullDN = array( "ApacheDS"=>true ); 
$wgLDAPLowerCaseUsername = array( "ApacheDS"=>true); 
$wgLDAPGroupObjectclass = array( "ApacheDS"=>"groupofuniquenames" );
$wgLDAPGroupAttribute = array( "ApacheDS"=>"uniquemember" );
$wgLDAPGroupNameAttribute = array( "ApacheDS"=>"cn" );

$wgLDAPRequiredGroups = array( "ApacheDS" => 
    array("cn=WikiUsers,ou=groups,o=wiki,dc=mywiki,dc=com"));
$wgLDAPGroupSearchNestedGroups = array( "ApacheDS"=>false );

As you can see, all the entries are variables that are assigned to arrays. In each array, an entry is assigned to a key that is the name that you have chosen for the $wgLDAPDomainNames variable.

The information shown in Table 2 configures the domain and host information.

Table 2. The variables that are used to configure the domain and host information
ConfigurationDescription
$wgLDAPDomainNamesThe name of the realm for authentication. These elements display to the users in the drop-down box, so choose names that are meaningful to the users. The names can be any arbitrary values, but the other configuration keys use these names in their arrays.
$wgLDAPServerNamesThe host names of the servers on which the LDAP services are running.
$wgLDAPPortThe port for LDAP, if the port is a non-standard port. Because the default LDAP port (389, 636 for LDAP over SSL) is below 1024, you may need elevated privileges to bind to the port.
$wgLDAPEncryptionTypeThe type of encryption to use for the LDAP connection. Do not use anything other than tls or ssl in a production deployment or when you're using actual user information.

After you have the domain and host information configured, you can set up a user with which to bind to the LDAP directory. Alternatively, you can allow anonymous access, but that might not align with your security goals. The proxy user settings are shown in Table 3.

Table 3. Setting up a proxy user to bind to LDAP
ConfigurationDescription
$wgLDAPProxyAgentThe complete DN for the user to use for binding to LDAP. Do not use the LDAP administrative user.
$wgLDAPProxyAgentPasswordThe password for the proxy user.

After you successfully bind to the LDAP directory with the proxy user, you need to specify base DNs in which to search for the user information. These configuration settings are explained in more detail in Table 4.

Table 4. The configuration settings for base DNs
ConfigurationDescription
$wgLDAPGroupUseRetrievedUsernameSet this to true to use the name of the user as retrieved from LDAP. This helps ensure the correct value is used when filtering for groups that contain the user.
$wgLDAPSearchAttributesThe name of the LDIF field to search using the login name. Most often, this should be uid.
$wgLDAPBaseDNsThe base DN to use for searches. You should set this to your domain or organization's DN.
$wgLDAPGroupBaseDNsThe base DN for the groups in the LDAP directory.
$wgLDAPUserBaseDNsThe base DN in which users are stored in the LDAP directory.

Group access is controlled by the settings shown in Table 5.

Table 5. The configuration settings for group-based authentication
ConfigurationDescription
$wgLDAPGroupUseFullDNIf set to true, the full DN of the group is used for binding. Because you're being specific in the name of the group, use true here.
$wgLDAPLowerCaseUsernameConverts or keeps the user's login name in lowercase if set to true.
$wgLDAPGroupObjectclassThe name of the object class of the group that contains your users. The examples in this article use the groupOfUniqueNames class. You can type the value in all lowercase here.
$wgLDAPGroupAttributeThe field to look for in the group to find the user's DN. For the groupOfUniqueNames class, this is the uniqueMember field. The value can be lowercase.
$wgLDAPGroupNameAttributeThe group name attribute. In the examples in this article, the attribute is cn.
$wgLDAPRequiredGroupsThis variable allows you to restrict access by group. This should be the full DN of the group containing the users able to access to your MediaWiki installation.
$wgLDAPGroupSearchNestedGroupsUnless you know that you have nested groups, keep this value as false for performance reasons.

Now that you have configured the LDAP authentication module for MediaWiki, go to your MediaWiki site and attempt to log in to MediaWiki using one of the users that you created. If all goes well, MediaWiki logs you in and you are now an authenticated user. If you get an error in your login attempt, see the "Troubleshooting" section to learn more about what you can do to track down the source of the error.


Security

For ease of use and testing, the LDAP example in this article is done in clear text. However, this is certainly not a recommended practice for a production system. Transmitting information in clear text allows people who know how to do so to "snoop" on the conversation between MediaWiki and the LDAP server. The people snooping on the connection can obtain user and password information, and this can lead to catastrophic results for your organization.

Before deploying an LDAP authentication solution to production, make sure you change the $wgLDAPEncryptionType variable to tls or ssl. I tested the MediaWiki-to-LDAP authentication in clear text using virtual machines that were isolated in a host-only network, which allowed me to do realistic testing but without exposing any information to snoopy outsiders. It is often easier get everything working first and then implement a Secure Sockets Layer (SSL) encryption solution because encryption comes with challenges of its own. During setup, you want to make sure that you're actually debugging LDAP problems and not security certificate problems.


Troubleshooting

One of the benefits of using the ApacheDS stand-alone server is that you can easily modify the logging properties files to display detailed debug information to the console. Even if you end up using a different LDAP directory for your production needs, being able to see debugging information on the server side allows you to determine if the base DNs and other properties that you specified are set up correctly. As you make queries to find users and groups, the DNs and filters for the queries are printed to the console output of the server along with the results of the search.

Debugging on the server also allows you to make sure the connection is being made correctly. If you're having problems binding to the LDAP directory, verifying that the connection is being made correctly is the first step you should take.

In addition, you can turn debugging on for the MediaWiki LDAP authentication module. The two entries that you add to your LocalSettings.php file to show debugging are shown in Listing 3.

Listing 3. Adding configuration in LocalSettings.php for debugging
$wgLDAPDebug = 5;
$wgDebugLogGroups["ldap"] = "/tmp/ldap.log";

Be aware of who can view this debugging information. If you set the debugging level higher than 3, the LDAP authentication module prints sensitive information to the logs. You need to make sure that these values are commented out in a production instance so that no sensitive information is printed to the logs.


Summary

MediaWiki is a PHP solution you can use to allow users to easily edit and publish their own content on the Web, making it an ideal solution for internal knowledge bases and information sharing. Knowledge-sharing solutions bring concerns about access to edit data, which is where LDAP comes in handy. An LDAP solution allows you to centrally manage users and groups in a standardized format that can be accessed from a wide variety of clients.


Download

DescriptionNameSize
Sample LDIF fileExample.zip1KB

Resources

Learn

Get products and technologies

Discuss

  • Get involved in the developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=791309
ArticleTitle=Integrating MediaWiki with LDAP
publish-date=02072012