Integrating MediaWiki with LDAP
Use ApacheDS to test and configure LDAP authentication with MediaWiki
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 Related topics for links.
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 Related topics).
You can download MediaWiki free (see Related topics). The download includes a high-level overview about installing MediaWiki on your system.
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.
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
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
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 Related topics).
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 Related topics). 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
- Select LDAP > New Entry.
Select Create entry from scratch as shown in Figure 2.
Figure 2. Creating a new entry from scratch
inetOrgPersonobject class as shown in Figure 3, and then click Next.
Figure 3. Adding the
Add a unique user name assigned to the
uidas shown in Figure 4, and then click Next.
Figure 4. Defining the
uidfield for the new user
Add the values for the
snfields 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.
Figure 6. 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
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
Now follow the same steps you used when setting up the user, except define
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
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.
To install MediaWiki, download the archive file from the MediaWiki site (see Related topics). The high-level steps for installing MediaWiki are:
- Extract the contents of the archive file into a folder available to your web server.
- In your browser, navigate to the config directory (for example, http://localhost/mediawiki/config/index.php).
- The MediaWiki installer will walk you through the rest of the steps.
To get more information about installing MediaWiki, see Related topics 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 Related topics) 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.
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
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
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
|uid||editor1||The unique identifier for the user name, usually the user's login name.|
|ou||users||The name of the organizational unit to which the user belongs.|
|o||wiki||The name of the organization.|
|dc||dc=mywiki,dc=com||The domain component for
the organization. This usually maps to the Internet domain
name. For example, this |
Groups are specified much like users, where the field that identifies the
group uniquely might be the common name (
cn) field instead of
uid. An example group DN is
See Related topics 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
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
|$wgLDAPDomainNames||The 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.|
|$wgLDAPServerNames||The host names of the servers on which the LDAP services are running.|
|$wgLDAPPort||The 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.|
|$wgLDAPEncryptionType||The type of encryption to use
for the LDAP connection. Do not use anything other than
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
|$wgLDAPProxyAgent||The complete DN for the user to use for binding to LDAP. Do not use the LDAP administrative user.|
|$wgLDAPProxyAgentPassword||The 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
|$wgLDAPGroupUseRetrievedUsername||Set 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.|
|$wgLDAPSearchAttributes||The name of the LDIF field to
search using the login name. Most often, this should be
|$wgLDAPBaseDNs||The base DN to use for searches. You should set this to your domain or organization's DN.|
|$wgLDAPGroupBaseDNs||The base DN for the groups in the LDAP directory.|
|$wgLDAPUserBaseDNs||The 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
|$wgLDAPGroupUseFullDN||If 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.|
|$wgLDAPLowerCaseUsername||Converts or keeps the user's login name in lowercase if set to true.|
|$wgLDAPGroupObjectclass||The name of the object class
of the group that contains your users. The examples in this
article use the |
|$wgLDAPGroupAttribute||The field to look for in the
group to find the user's DN. For the
|$wgLDAPGroupNameAttribute||The group name attribute. In
the examples in this article, the attribute is
|$wgLDAPRequiredGroups||This 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.|
|$wgLDAPGroupSearchNestedGroups||Unless 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.
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
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.
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.
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.
- Visit Wikipedia:Statistics to see how many pages and users are served with MediaWiki.
- 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.
- 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.