It's better when it's simple

User Tools

Site Tools



:!: This is an old authentication backend and works with dokuwiki up to Andora Belle 2012-10-13

For newer dokuwiki releases an auth plugin is required.

You have to convert this backend to an auth plugin as it is unknown if there is an alternative or successor (as successor of external)

Calls an external application and passes the password to it on standard input.

author: Zbigniew Jędrzejewski-Szmek

lastupdate : 2009-11-07

Download and Installation

The reason for this plugins existence is the need to authenticate through PAM. However, I didn't want to give the privilege to read encrypted passwords to the user that the Apache web server (and DokuWiki) run as. The setup goes as this:

  1. external.class.php is installed in inc/auth and DokuWiki authentication is set to 'external'
  2. the user running the webserver (usually something like www) is given the ability to execute a second program with elevated privileges. I used a program written in python, i.e. a script, so a simple set-uid will not work. I had to resort to sudo. Put this in /etc/sudoers:
    www    ALL = (ALL) NOPASSWD: /usr/bin/python /usr/local/bin/
  3. install a program to do the actual password verification. It must read two lines from stdin, the JSON encoded username and the JSON encoded password. The password and username have to be somehow escaped so e.g. newlines in the password don't mess things up. JSON is simple and standard.

Using not a Python script but a real binary would have the advantage of not having to use sudo. A simple

  chgrp root.www /path/to/binary
  chmod u+s,g+x,o= /path/to/binary

should be enough.

The support for PAM is very primitive – an echoed prompt is assumed to be a request for the username, an non-echoed prompt is assumed to be the request for a password. The user information is duplicated: in dokuwiki and in the /etc/group, /etc/shadow. The password stored in the dokuwiki user database is ignored, and the one from /etc/group or /etc/shadow is used. Nevertheless, users must be created in both places.

DokuWiki plugin code: external.class.php

 * external authentication backend                                         
 * @author Zbigniew Jędrzejewski-Szmek <>                 
 * based on work by Michael Gorven <>         
 * @license GPL2                      
define('DOKU_AUTH', dirname(__FILE__));
class auth_external extends auth_plain
     * Constructor                    
     * Calls the auth_plain constructor which sets the backend's capabilities.
     * The change password capability is then removed since we can't change   
     * passwords through PAM without knowing the current password.            
    function auth_pam()                                                       
        // Call parent constructor                                            
        if (method_exists($this, 'auth_plain'))                               
        // Remove change password capability
        $this->cando['modPass'] = false;    
     * Checks the provided username and password using PAM.
     * @param   string  $user   Username                   
     * @param   string  $pass   Password                   
     * @return  boolean True if authentication is successful
    function checkPass( $user, $pass )                      
        // Check that user exists                           
        if ( parent::getUserData($user) === false )         
            return false;                                   
        $userenc = json_encode($user) . "\n";
        $passenc = json_encode($pass) . "\n";
        $external_cmd = 'sudo /usr/bin/python /usr/local/bin/';
        // Check password
        $handle = popen($external_cmd, 'w');
        fwrite($handle, $userenc);          
        fwrite($handle, $passenc);          
        $ret = pclose($handle);
            return false;
        // Authentication succeded
        return true;
     * Creates a new user.
     * Uses the createUser() method in auth_plain to actually add the user.
     * This only adds the user to the list of DokuWiki users -- they must
     * separately be added to PAM and assigned a password.
     * @param   string  $user   Username
     * @param   string  $pass   Password (will be blank)
     * @param   string  $name   Full name
     * @param   string  $mail   Email address
     * @param   string  $grps   List of groups
     * @return  bool    False if user already exists, null if error occurred, true if successful
    function createUser($user,$pwd,$name,$mail,$grps=null)
        // createUser() returns the password if successful. We therefore need to
        // set it to something non-empty otherwise it gets treated as false
        return parent::createUser( $user, time(), $name, $mail, $grps );

Helper script:

Requires simplejson and python-pam (the module is called PAM). Not to be confused with a different module based on ctypes called pam.
__version__ = '0.2'
import sys
import PAM
import errno
import simplejson
username = ''
password = ''
service = 'passwd'
def pam_conv(auth, query_list, userData=None):
        resp = []              
        for query,type in query_list:
                if type == PAM.PAM_PROMPT_ECHO_ON:
                        resp.append((username, 0))
                elif type == PAM.PAM_PROMPT_ECHO_OFF:
                        resp.append((password, 0))   
                elif type == PAM.PAM_PROMPT_ERROR_MSG or type == PAM.PAM_PROMPT_TEXT_INFO:
                        print >>sys.stderr, 'pamlogin: query (%s)' % query                
                        resp.append(('', 0));                                             
                        return None                                                       
        return resp
def authenticate():
    auth = PAM.pam()
    auth.set_item(PAM.PAM_USER, username)
    auth.set_item(PAM.PAM_CONV, pam_conv)
    except PAM.error, (resp, code):
        print >>sys.stderr, 'pamlogin: auth failed (%s)' % resp
        return False
    return True
def read_user_pass():
    userenc = raw_input()
    passenc = raw_input()
    global username, password
    username = simplejson.loads(userenc)
    password = simplejson.loads(passenc)
def main():
    if authenticate():
        return 0
        return errno.EPERM
if __name__ == '__main__':
  • version 0.2: add explicit __version__, support three parameter pam_conv() from newer python-pam
  • version 0.1: initial version



Become the user running the webserver and call the authentication program. Give JSON encoded username into its input (with extra quotes coming from JSON):

www$ sudo python /path/to/ && echo OK 

If you don't see OK, then check syslog for messages.

python: pam_unix(passwd:auth): conversation failed

The error string 'conversation failed' means a problem between the Python script and PAM system. Not being able to open /etc/shadow or some other problem with permissions gives a different error.

auth/external.txt · Last modified: 2021-08-18 00:42 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki