# Pluggable Authentification for the Contenido Backend (V. 4.8.x)

## Introduction

Contenido introduces a new system to authenticate against external sources (LDAP directories, for example).

## What does it do?

Contenido Pluggable Authentification Modules (don't swap them around with Linux PAM) makes it possible to authenticate via external sources - and just authentification.

## How it works (authentification handler)

To write your own authentification handler, you have to write a single function which looks like this:

    function active_directory_auth ($username, $password)
    {
    	global $cfg;

    	if ($cfg['ldap']['server'] != "")
    	{
        	$ad = ldap_connect($cfg['ldap']['server']);
        	if ($ad)
        	{
        		ldap_set_option($ad, LDAP_OPT_PROTOCOL_VERSION, 3);
        		$bd = ldap_bind($ad, $username . $cfg['ldap']['suffix'], $password);

        		if (!$bd)
        		{
        			return false;
        		}
        	}
    	}

    	return true;
    }

If that function returns true, the mechanism knows that the login was successful. After that, you have to register the function:

    register_auth_handler("active_directory_auth");

By registering the function, the login mechanism knows that it should call "active_directory_auth" for certain users. Finally, you have to include your new handler file (the recommended place is config.local.php).
The login mechanism knows that you want to use a registered auth handler if the entry in the password field of the user equals a registered auth handler; e.g. the user "test" has "active_directory_auth" in his password field, thus the login mechanism would use the "active_directory_auth" function to validate. The password field has to be set using the sync script.

## Syncing with a remote source

To make the authentification handler working, you have to "sync" your users to Contenido. This means that each user needs to be created and/or updated by a sync script (it's preferred to automate this using a cronjob to ensure regular updates). The active directory example has a sync script; you can modify it to fit your own needs.
Remember that if you want your permissions syncronized using the sync script, you are on your own - we recommend that you only sync users, user-to-group relationships and groups and apply all rights to groups to keep it simple.