External authentication with SemanticScuttle

Most times, one piece of software is only a part in the big puzzle that makes the software landscape of a company or organization. SemanticScuttle is not different and should integrate as nicely as possible with all other systems.

One of the basic tasks of integration is user authentication against a central database - be it a central user database, an LDAP or a active directory server.

Since version 0.96, SemanticScuttle supports user authentication against external systems. To provide a wide range of supported systems, we chose to utilize PEAR's Authentication package. It does this by providing different "authentication containers", for example Database, IMAP, LDAP, POP3, RADIUS, SAP and SOAP.

Please be aware of the fact that, after successful authentication, the user and his scrambled password are stored in the SemanticScuttle database. This is required for proper functioning of the software. It does not mean that you will be able to login if your external authentication provider is offline - you won't, execpt you switch it off in the SemanticScuttle configuration.

Basic configuration

The default configuration file data/config.default.php has an own section on auth options and an explanation of the single entries.

To utilize the external authentication, you need to install the PEAR Auth package:

$ pear install auth

If you do not have a PEAR installation available, you can try to manually install the files in the src/ directory. If you choose to do that, the src/ directory should look similar to that:

src/
 Auth.php
 Auth/
  Anonymous.php
  Container.php
  Container/
  ..
 SemanticScuttle/
  header.php
  ..

After that, modify your data/config.php file. The most important change is to use

$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';

which tells SemanticScuttle to switch to the special authentication service.

Now that's done, you can configure the single auth options:

$authType = 'MDB2';

selects the authentication container.

$authOptions

is an array of options specific to the authentication container. Please consult the PEAR Auth documentation for more information.

$authDebug = true;

should be used when setup fails, since it may give important hints where it fails.

Please note that login will seem to fail with debugging activated. Going back to the main page after that will show that you are logged in.

Authentication examples

General database authentification

Here you also need the PEAR MDB2 package. The "new_link" option is important!

config.php settings:

$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
$authType = 'MDB2';
$authOptions = array(
    'dsn' => array(
        'phptype'  => 'mysql',
        'hostspec' => 'FIXME',
        'username' => 'FIXME',
        'password' => 'FIXME',
        'database' => 'FIXME',
        'new_link' => true,
    ),
    'table'       => 'usersFIXME',
    'usernamecol' => 'usernameFIXME',
    'passwordcol' => 'passwordFIXME',
    'cryptType'   => 'md5',
);

Mantis Bugtracker

Here you also need the PEAR MDB2 package.

config.php settings:

$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
$authType = 'MDB2';
$authOptions = array(
    'dsn' => array(
        'phptype'  => 'mysql',
        'hostspec' => 'FIXME',
        'username' => 'FIXME',
        'password' => 'FIXME',
        'database' => 'FIXME',
        'new_link' => true,
    ),
    'table'       => 'mantis_user_table',
    'usernamecol' => 'username',
    'passwordcol' => 'password',
    'cryptType'   => 'md5',
);

MediaWiki

Unfortunately, the password column does not contain a simple hashed password - for good reasons as described on http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column

If you configure your MediaWiki to use passwords without salt, you can make it work nevertheless:

MediaWiki LocalSettings.php:

$wgPasswordSalt = false;

- after that, users need to change/update their passwords to get them unsalted in the database. You can verify if the passwords are unhashed if you do

SELECT CAST( user_password AS CHAR ) FROM user

on your MediaWiki database. Passwords prefixed with ":A:" can be used.

Another problem is that mediawiki user names begin with an uppercase letter. You need to modify www/login.php and remove the "utf8_strtolower" function call:

$posteduser = trim(utf8_strtolower(POST_USERNAME));

becomes

$posteduser = trim(POST_USERNAME);

config.php settings:

$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
$authType = 'MDB2';
$authOptions = array(
    'dsn' => array(
        'phptype'  => 'mysql',
        'hostspec' => 'FIXME',
        'username' => 'FIXME',
        'password' => 'FIXME',
        'database' => 'FIXME',
        'new_link' => true,
    ),
    'table'       => 'user',
    'usernamecol' => 'user_name',
    'passwordcol' => 'user_password',
    'cryptType'   => 'md5_mediawiki',
);
function md5_mediawiki($password) {
    return ':A:' . md5($password);
}

Active Directory / LDAP

Here we authenticate against an active directory server.

config.php settings:

$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
$authType = 'LDAP';
$authOptions = array(
    'host'     => '192.168.1.4',
    'version'  => 3,
    'basedn'   => 'DC=EXAMPLE,DC=ORG',
    'binddn'   => 'readuser',
    'bindpw'   => 'readuser',
    'userattr' => 'sAMAccountName',
    'userfilter' => '(objectClass=user)',
    'attributes' => array(''),
);
$authEmailSuffix = '@example.org';

More LDAP options can be found in the PEAR manual.