Articles November 11, 2004 at 4:06 pm

Running MRBS on Mac OS X with LDAP Authentication

Who needs Exchange? With MRBS you can do your resource scheduling for less.

A walk-through of how to set up and configure an interesting open source meeting room, or other resource, web-based scheduling solution.MRBS (Meeting Room Booking
System) is a free GPL web application using PHP and MySQL for booking meeting
rooms. We have found it extremely helpful not only for booking rooms
but for signing out computer equipment, books, digital cameras, or any
shared resource.

MRBS supports many authentication schemes including a simple table,
POP3, IMAP, NIS, Netware, and LDAP. Now that Macintosh Server uses
OpenLDAP by default, I will go
through the steps needed to get MRBS up and running on an OS 10.3 server
and authenticating against an Open Directory master through LDAP.

In this article I will install MRBS version 1.2 on an Apple G4 running
Mac OS 10.3.5 Server and have it authenticate to a different OS X Server
acting as the Open Directory Master.

1. Preparing the Server

MRBS is written in PHP, a widely used scripting language especially
suited for web development. The data gets stored in a database, either
PostgreSQL or MySQL. In this example I will be using MySQL.

First, lets enable PHP. Open the Server Admin program and choose the
Web service. Click the Settings button and then the Modules tab at the
top. We need to turn on the PHP module so put a check in the box next
to php4_module and click Save.

Next, lets turn off the Performance Cache. The Performance Cache
requires opening an additional port on your firewall (16080) and keeps
some very large cache files. It makes sense for some sites but if you
are unsure, I suggest you turn it off. Lets try to keep things simple
for now.

Click the Sites tab at the top. This is a list of your current
websites. If you are starting from scratch, you will only see one with
a * as the address. Highlight that site and click the Edit pencil
icon below. Now select the Options tab above and uncheck
Performance Cache. Click Save at the bottom.
Now we can start the apache web server by clicking the green start
button at the top of the Server Admin window.

We also need to enable MySQL, the database we will be using. Mac 10.3
Server comes with a very basic GUI for the MySQL service. It is located
in /Applications -> Server -> MySQL Manager. First, you will
need to unlock and authenticate the MySQL Manager by clicking on the
lock icon. Click Install to set up MySQL on your server. Then you can
click Start.

2. Installing MRBS

Next we need to download MRBS and install it. For this example I will
be installing mrbs-1.2 You will notice two
packages available for download, mrbs, and mrbs-dev. You want the mrbs
version, the dev package is for developers.

I chose mrbs-1.2.tar.gz and StuffIt Expander unpacked it for me, leaving
a folder called mrbs-1.2 on my desktop. This folder contains
various sql tables for setting up our database, a web folder with the
php code, as well as some excellent documentation. It is a good idea to
read through the INSTALL and README files found in the mrbs-1.2
folder. Installation is as easy as just copying the web folder
to a location my web server can find it.

On a default OS X Server installation the root of the web server is
/Library/WebServer/Documents, so if you go to the web address
http://yourserver.yourdomain.com, you will see the contents of
this folder (probably the index.html file.) I am going to store my MRBS
files in a folder called Rooms. So my installation of MRBS can be found
at http://myserver.mydomain.com/Rooms/. You can use MRBS or whatever
name you want. Now we need to copy the contents of the web
folder from mrbs-1.2 to this new location. First I will change
my working directory (cd) to the mrbs-1.2 folder. Then copy the files
we need.

   brad$ cd Desktop/mrbs-12
    brad$ cp –r web /Library/WebServer/Documents/Rooms

3. Setting up the Database

Now that all the PHP files are in place, we can setup the database. The
MySQL root account password is left blank by default so lets change that
first.

   brad$ mysqladmin –u root –p password 'new_password'
    Enter password:  

Now login to the MySQL database as root, the –u flag tells MySQL we
will be specifying a user, in this case the root user. The –p flag
tells MySQL to prompt us for a password. The MySQL at the end of the
command tells the program which database we want to start with, in this
case the mysql database which stores the MySQL users.

   brad$ mysql -u root -p mysql
    

First, we need to create the mrbs database, which will store all
of our booking data.

   mysql> create database mrbs;

Lets add a user called mrbs_user and set the password for the
user. Be sure to replace your server and domain name where I
use my server: playground.plumblossom.org! Ed. Note: The first two lines here are wrapped.

    mysql> grant all on mrbs.* to mrbs_usr@localhost identified by 
        'mrbs-password'; 
    mysql> grant all on mrbs.* to [email protected] 
        identified by 'mrbs-password';
    mysql> exit;

Now we can import the sql tables provided for us in the mrbs-1.2
folder. This time, when you are prompted for a password, you can enter
the mrbs-password for our new mrbs_usr account.

   brad$ mysql -u mrbs_usr -p mrbs 

4. Configuring MRBS

Now that our MySQL database is setup we can configure MRBS to work with our server. There are two files we need to make changes to. The first is config.inc.php so start by changing directories to the new Rooms folder or your equivalent. Lets make a copy of this file for future reference.

   brad$ cd /Library/WebServer/Documents/Rooms
    brad$ cp config.inc.php config.inc.php.orig

The other file we are going to work with is auth_ldap.inc so we should definitely make a copy of it too.

   brad$ cp auth_ldap.inc auth_ldap.inc.orig

Lets start with the configuration file config.inc.php, go ahead and open it up with your favorite text editor. As you can see there are many options, I am only going to focus on the essential changes needed to get the service up and running. You come back to this file later if you want to further customize your site.

In the first section, we can enter the information necessary to connect to our MySQL database:

###################
# Database settings
###################
# Which database system: "pgsql"=PostgreSQL, "mysql"=MySQL
$dbsys = "mysql";
# Hostname of database server. For pgsql, can use "" instead of localhost
# to use Unix Domain Sockets instead of TCP/IP.
<b>&#36;db_host = "playground.plumblossom.org";</b>
# Database name:
&#36;db_database = "mrbs";
# Database login user name:
<b>&#36;db_login = "mrbs_usr";</b>
# Database login password:
&#36;db_password = "mrbs-password";

Next we can move down to the Site Identification section. You can add your company name and other information here if you want. It is a good idea to change the URL base to the full name of the server.

################################
# Site identification information
#################################
<b>&#36;url_base = "http://playground.plumblossom.org/Rooms";</b>

Now we can scroll down to the Authentication section. Pay attention to the lines in bold. In some of the lines, I just added a pound symbol at the beginning. The pound symbol makes the line a comment. A comment is intended to be read by a person so the computer will skip over any line beginning with a pound sign. This is a good way to leave notes for yourself or anyone else who may modify the file.

###############################################
# Authentication settings - read AUTHENTICATION
###############################################
&#36;auth["session"] = "php"; 
    # How to get and keep the user ID. One of
    # "http" "php" "cookie" "ip" "host" "nt" "omni".
<b>&#36;auth["type"] = "ldap";</b> 
    # How to validate the user/password. One of "none"
    # "config" "db" "pop3" "imap" "ldap" "nis" "nw" "ext".

# The list of administrators (can modify other peoples settings)
&#36;auth["admin"][] = "127.0.0.1"; 
    # localhost IP address. Useful with IP sessions.
<b>&#36;auth["admin"][] = "bschonhorst";</b>     
    # A user name from the user list. Useful 
    #with most other session schemes.
<b># two other users I want to give admin access to
&#36;auth["admin"][] = "michael"; 
&#36;auth["admin"][] = "jess";</b>

#&#36;auth["admin"][] = "10.0.0.1";
#&#36;auth["admin"][] = "10.0.0.2";
#&#36;auth["admin"][] = "10.0.0.3";
# 'auth_config' user database
# Format: &#36;auth["user"]["name"] = "password";
<b>#&#36;auth["user"]["administrator"] = "secret";
#&#36;auth["user"]["alice"] = "a";
#&#36;auth["user"]["bob"] = "b";</b>

# 'session_http' configuration settings
&#36;auth["realm"]  = "mrbs";

Now we can direct MRBS to our LDAP server. This could be the same machine MRBS is running on or a separate server. In this example my LDAP server (or Open Directory Master) is called bean.plumblossom.org.

# 'auth_ldap' configuration settings
# Where is the LDAP server
<b>&#36;ldap_host = "ldap://bean.plumblossom.org/";</b>
# LDAP base distinguish name 
# See AUTHENTICATION for details of how to check against multiple base dn’s
#&#36;ldap_base_dn = “ou=organizationalunit,dc=my-domain,dc=com”;
# Attribute within the base dn that contains the username
#ldap_user_attrib = “uid”;
<b>&#36;ldap_base_dn=“cn=users,dc=plumblossom,dc=org”;</b>

Towards the bottom of the file is one more section that needs our attention. The PHP module that is installed by default in 10.3 Server does not support the iconv module which gives MRBS the ability to easily support languages other than English. We will turn it off in this example. If you are using another language you may need to reinstall PHP on your server (with the iconv module) and then turn this feature back on.

##########
# Language
##########

# Set this to 1 to use UTF-8 in all pages and in the database, otherwise
# text gets enterered in the database in different encodings, dependent
# on the users' language
<b>&#36;unicode_encoding = 0;</b>

That’s all we need to do to that file, make sure to save your changes. Now lets take a look at the file that actually connects to our LDAP server to authenticate our users. Open auth_ldap.inc with a text editor.

This file contains two functions, the first is authValidateUser($user, $pass) which verifies the username and password against our LDAP server. The second is authGetUserLevel($user) which checks config.inc.php to see if the username was listed as an admin account. (Remember where I added michael and jess.) We are going to replace the first function and leave the second one alone. Below is a different version of the authValidateUser function that should make LDAP authentication work with your 10.3 server. To remove the current version start deleting at the line that reads:/authValidateUser($user, $pass) and continue until you reach the second function beginning with /authGetUserLevel($user). Then you can add our new version.

/* authValidateUser(&#36;user, &#36;pass)
 * 
 * Checks if the specified username/password pair are valid
 * 
 * &#36;user  - The user name
 * &#36;pass  - The password
 * 
 * Returns:
 *   0        - The pair are invalid or do not exist
 *   non-zero - The pair are valid 
 *
 *   Altered by Brad Schonhorst for Mac OS 10.3 integration 
 */
function authValidateUser(&#36;user, &#36;pass)
{
    global &#36;auth;
    global &#36;ldap_host;
    global &#36;ldap_base_dn;
    global &#36;ldap_filter;

    // Check if we do not have a username/password
    // User can always bind to LDAP anonymously with empty password,
    // therefore we need to block empty password here...
    if(!isset(&#36;user) || !isset(&#36;pass) || strlen(&#36;pass)==0)
    {
        return 0;
    }
// Check if &#36;pass equal to "userPassword" attribute in &#36;dn
    &#36;ldap=@ldap_connect(&#36;ldap_host);
    if(&#36;ldap)
    {
        ldap_set_option(&#36;ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
        &#36;dnuser="uid=&#36;user, &#36;ldap_base_dn";
        &#36;r=@ldap_bind(&#36;ldap,&#36;dnuser,&#36;pass);
        if(&#36;r)
         {
            @ldap_unbind(&#36;ldap);
            return 1;
         }
        else{
           // no DN round -&gt; unknown ldap user
            authGet(&#36;auth["realm"]);
            return 0;
        }
    }
   else{
     return 0;
  }
}

5. Try it!

After making all of the above changes, MRBS should now be up and running on your server and allow you to authenticate against your 10.3 LDAP server. Only users listed as admins can add or remove rooms. Anyone else in your LDAP server can login and check out a space! If you plan on making your implementation of MRBS available over the internet, you may wish to implement SSL on your web server as an added layer of security.

No Comments

  • I just thought I’d point out that it is almost easier to install a more complete
    php, and then you don’t need to touch the MRBS source at all.

    I use Marc’s version from entropy.ch
    and MRBS works seamlessly for me with Open Directory authentication,
    without having to touch the source.

    • If you want to do filtering for certain groups, etc., you also need to
      change
      the config.inc.php file. There’s a typo on line 223… by default (version 1.2.3)
      it reads:

      #$ldap_user_filter = "mrbsuser=y";

      Obviously, to use the filter, you need to uncomment the line, but it needs
      to be something like:

      $ldap_filter = "gidNumber=20";

      This filter would force the user’s primary group ID to be 20 (staff). You can
      change it to use any LDAP field and value you want to filter on.

      You also need to add the

      ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3)

      line to the auth_ldap.inc file (as mentioned in the previous
      comment) to make this work.

Leave a reply

You must be logged in to post a comment.