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.

Back to top

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.

Back to top

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.

Back to top

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.

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.

Back to top

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
   
   
   

3. Add the inetOrgPerson object class as shown in Figure 3, and then click Next.

   
   
   Figure 3. Adding the inetOrgPerson object class
   
   
   

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
   
   
   

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
   
   
   

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

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.

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.

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.

Back to top

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.

Back to top

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.

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.

Back to top

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.

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.

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.

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.

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.

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

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.

Back to top

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.

Back to top

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.

$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.

Back to top

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.

Back to top

Download

Information about download methods

Resources

Learn

• Visit Wikipedia:Statistics to see how many pages and users are served with MediaWiki.
  
  
• Learn how to configure and use ApacheDS from the ApacheDS v1.5 Basic User's Guide.
  
  
• Read the MediaWiki Installation Guide for more information about installing MediaWiki.
  
  
• Visit the Wikipedia entry about LDIF to learn more about the LDAP data interchange format.
  
  
• Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  
  
• Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools as well as IT industry trends.
  
  
• Follow developerWorks on Twitter .
  
  
• Watch developerWorks on-demand demos ranging from product installation and setup demos for beginners, to advanced functionality for experienced developers.
  
  

Get products and technologies

• Download MediaWiki from the official site.
  
  
• Download ApacheDS as a stand-alone server or plug-in to Eclipse.
  
  
• Install the MediaWiki LDAP authentication module from the Extension:LDAP_Authentication page.
  
  

Discuss

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

About the author

Nathan 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.

Rate this article

Comments

Back to top

Table of contents

• Before you begin
• MediaWiki
• ApacheDS
• Install ApacheDS
• Set up users and groups
• Install MediaWiki
• Install the MediaWiki LDAP module
• Configure authentication
• Security
• Troubleshooting
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, Zend Core PHP, and Java you can develop advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data and powering a new breed of SOA and Web 2.0 solutions.
• Article: This IBM Redbook shows how to port PHP apps from MySQL to DB2, and includes code samples for creating Zend Core PHP applications.
• Tutorial: In this Mastering Facebook app development tutorial series, you will use Java and PHP in parallel to build a Facebook interface for an online stock trading J2EE application using the Spring framework.
• Buy: DB2 9 for Linux, UNIX and Windows

Dig deeper into Open source on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers