DokuWiki

It's better when it's simple

Outils pour utilisateurs

Outils du site


Panneau latéral

Traductions de cette page?:

Découvrir DokuWiki

Options avancées

Pour les entreprises

Notre Communautée


Suivez-nous sur Facebook, Twitter et les autres résaux sociaux.

Notre politique de confidentialité

fr:devel:auth_plugins

Extension d'authentification

:!: Traduction en cours :!:

Les informations contenues sur cette page concernent les versions 2013-05-10 “Weatherwax” et plus récentes

Pour les versions plus anciennes telles que 2012-10-13 “Adora Belle” voir :
- Développement d'anciens authentication backends
- Anciens modules d'authentification auth

Ci-dessous la première version de la documentation pour le développement d'extensions d'authentification. Il est donc possible qu'elle contienne des erreurs ! Merci de les signaler, tout retour est le bienvenu.

Le système d'authentification de DokuWiki est extrèmement modulaire et peut, de manière générale, authentifier les visiteurs en utilisant tout ce qui est accessible à PHP. Auth Plugins liste les extensions d'authentification.

D'une part, vous pouvez créer un greffon qui implémente toutes les méthodes dont DokuWiki a besoin pour vérifier les utilisateurs et rassembler les informations sur ces utilisateurs. D'autre part, vous pouvez utiliser la méthode trustExternal() qui remplace les fonctions d'authentification de DokuWiki. Vous gérer l'authentification dans cette méthode en appelant votre propre dorsal

Synopsis

Un Plugin d'authentication nommé Example a besoin de :

  • d'une classe nommée auth_plugin_authexample
  • et doit être stocké dans le fichier lib/plugins/authexample/auth.php.

Par ailleurs le fichier plugin.info.txt est nécessaire. Pour plus de détails sur les greffons et leurs fichiers, se référer à plugin_file_structure.

Implementation Requise

Vous devez au minimum implémenter deux champs et trois méthodes.

Champs:

  • $success
    Votre constructeur doit le positionner sur vrai si le module s'est correctement initialisé. Utiliser ce booléen pour notifier le frontal de DokuWiki que quelque chose s'est mal passé en le réglant sur faux.
  • $cando
    Tableau associatif de booléens indiquant les fonctionnalités que votre dorsal peux réaliser. Voici la liste des clefs de $cando et leur signification :
    • addUser – Peut-on créer des utilisateurs ?
    • delUser – Peut-on supprimer des utilisateurs ?
    • modLogin – Peut-on modifier les identifiants ?
    • modPass – Peut-on mpdifier les mots de passe ?
    • modName – Peut-on modifier le nom des utilisateurs ?
    • modMail – Peut-on modifier les adresses de courriel ?
    • modGroups – Peut-on modifier les groupes ?
    • getUsers – Peut-on obtenir une liste (filtrée) d'utilisateurs ?
    • getUserCount – Peut-on obtenir le nombre d'utilisateur ?
    • getGroups – Peut-on obtenir une liste de groupe ?
    • external – Le module procède-t-il à une authentification externe ?
    • logout – L'utilisateur peut-il se déconnecter ? (impssible avec HTTP auth, par exemple)

Méthodes:

Only a few functions need to be implemented. But the more you do the more the frontend will be able to do. See lib/plugins/auth.php for the methods' arguments and return values and for an example implementation see lib/plugins/authplain/auth.php the plain authentication backend, DokuWikis default.

  • __construct()
    Well your class should have a constructor of course :-) Set the fields $success and $cando mentioned above here.
  • checkPass($user, $pass)
    This function need to check if the given userid $user exists and the given plaintext password $pass is correct.
  • getUserData($user)
    Used to return user information like email address and real name, for the requested userid $user
    Return false or an array with at least the keys
    array(
        'name' => string,
        'mail' => string,
        'grps' => array()
    )

Optional implementation

All these methods are optional and will only be called if the appropriate $cando fields are set

  • trustExternal() (replaces DokuWiki authentication functions)
    If $cando['external'] is true, this method is used to authenticate a user – all other DokuWiki internals will not be used for authenticating. The function can be used to authenticate against third party cookies or Apache auth mechanisms and replaces the default auth_login() function from inc/auth.php.

    If this method is implemented you may omit the implementation of all the other methods from your module. You only really needs a constructor and this trustExternal() function, however it is strong recommended to have getUserData() so DokuWiki can display your users nicely and logoff() to permit DokuWiki to communicate the logoff to your backend. The other methods are only needed when you like that some internals of DokuWiki interact with your backend. Search the source code or browse on http://xref.dokuwiki.org/ to check out the connections.

    Have a look at the punbb backend for an example usage of this method. According to the example method in the parent auth_basic class the trustExternal() method has to set the global variables: $USERINFO, $SERVER and _SESSION[DOKU_COOKIE] for the indicated fields.

    The implementation depends very much on your backend, here are some often used parts indicated as example. Look also for other implementations, when it doesn't fit your requirements.
    function trustExternal($user, $pass, $sticky=false) {
        global $USERINFO;
     
        // someone used the login form
        if(!empty($user)){
            //situation: there are user credentials, lets check them
            if( ...try to authenticate again your backend...)
     
                // here you can handle additional post login actions 
                // for your backend
     
            }else{
                //invalid credentials - log off
                msg($lang['badlogin'],-1);
                auth_logoff(); // needs implementation of logOff() method
                return false;
            }
        }
     
        //situation: no login form used or logged in successful 
     
     
        // check where if there is a logged in user e.g from session,
        // $_SERVER or what your auth backend supplies...
     
        if( ...check here if there is a logged in user...) {
     
            $USERINFO['name'] = string
            $USERINFO['mail'] = string
            $USERINFO['grps'] = array()
     
            $_SERVER['REMOTE_USER']                = $user; //userid
            $_SESSION[DOKU_COOKIE]['auth']['user'] = $user; //userid
            $_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;
     
            return true;
        }else{
            //when needed, logoff explicitly.
        }

    For a description of the $USERINFO variables see the documentation of the getUserData() function. Do not forget to add global $USERINFO to the start of this function, to make the variable accessible.

    Another thing to keep in mind if you're implementing Single Sign On based on a cookie, is that if you want to be able to use DokuWiki's login form when SSO cookie is not present, you need to set that cookie once you verify the credentials, so on next page load you can authenticate based on that SSO cookie as $user and $pass variables will be empty since login form is not submitted. In punbb this is done with pun_setcookie() function call.

    Dokuwiki will not show any message if the login failed, therefore this method shall show some information using msg().

    Examples
    See also this working example of trustExternal().

    Some (old) backends using this function are: punbb, cas, cosign, plaincas, django, extdjango, gforge, http version of ggauth, keeyaiwp, mod_auth_tkt, ssp

  • logOff() (only when required/possible)
    Run in addition to the usual logoff. Useful with trustExternal() to initiate actions for the external backend e.g. use it to clear cookies or similar actions.
  • isCaseSensitive() (optional)
    When your backend is caseinsensitive, override it with a method that returns false.
  • cleanUser($user) (optional)
    Applied when username is given to and return from backend. Enforce here also username restrictions.
  • cleanGroup($group) (optional)
    Applied when groupname is given to and return from backend. Enforce here also groupname restrictions. Groupnames are to be passed without a leading '@' here.
  • useSessionCache($user) (only when required)
    DokuWiki caches user info for a timespan. This function check expiration of this caching.

Inherited methods

  • All the optional methods defined above are inherited methods, mostly these are a fallback warning explaining it's not implemented in your plugin yet.
  • canDo($cap) Checks capabilities set in $cando field, or the pseudo capabilities: Profile and UserMod.
  • triggerUserMod($type, $params) Triggers AUTH_USERDATA_CHANGE, which calls the methods defined on the current authentication plugin for the $type equal to: create, modify and delete where $params are type specific parameters.
  • See common plugin functions for inherited function available to all plugins. e.g. localisation, configuration and introspection.

Notes

Config loading sequence

At the moment, temporary, also the config of old style auth modules are loaded.
The loading order is:

  1. Default config settings
  2. Old style auth module config settings (i.e. $conf['auth']['yourauthbackend']))
  3. The current auth plugin settings (i.e. $conf['plugin']['yourauthplugin']).

Start session

Dokuwiki starts a session prior to using the authentication backend. If your framework uses specific session settings (e.g. another session path) use session_destroy() in the backend constructor and start your own session then (Note: not fully tested for side effects, yet!). FIXME is destroy & start again the same? side effects?

SUGGESTION: Do it require an own event or auth function to replace default sessionstart?

About autoloading

Your backend (or its framework) cannot use __autoload to include further classes, those classes must be loaded manually via require()

Handling of old auth backends

When you update your wiki to the 2013-05-10 “Weatherwax” release, you need an auth plugin for the authentication, because the authentication backends aren't supported anymore. The previous bundled authentication backends are already converted to auth plugins: AuthPlain, AuthMySQL, AuthPgSQL, AuthAD and AuthLDAP.

When you use another plugin than the bundled one, you need to check if someone has already shared the auth plugin version in the plugin repository. You can filter the plugins by Auth plugintype. Or you should rewrite the authentication backend yourself. See Howto update your old backend below.

Update wiki to new backend

When you used the plain authentication backend before, DokuWiki will pick up the new authplain due to DokuWiki's defaults are updated too. For all other values of the authtype configuration, you get the warning User authentication is temporarily unavailable. If this situation persists, please inform your Wiki Admin. and you cannot login anymore. This can be solved by updating the authtype configuration to the auth plugin version of your desired backend. When you use a not bundled auth plugin you should first install this one.

When your desired auth plugin is installed you can modify your the authtype configuration setting in conf/local.php (or conf/local.protected.php) by an editor on your server by prefixing your <authentication backend name> with auth to auth<authentication backend name>:

conf/local.php
...
// $conf['authtype'] = 'example';  //auth backend
$conf['authtype'] = 'authexample'; //auth plugin
...

Howto install an auth plugin via plugin manager without working backend?

When you prefer to install an auth plugin by the DokuWiki plugin manager, you need to switch to the plain authentication backend. You need access to the configuration file conf/local.php on you server. Open it in an editor and remove the line from conf/local.php or conf/local.protected.php:

// $conf['authtype'] = '...'; //disable your authtype config

or change that line to:

$conf['authtype'] = 'authplain';

and save the file. Now your wiki uses the AuthPlain plugin. Next you login as superuser. Hint: Probably you can login by the user you define on installation (the installer creates default that users as superuser). Now you can use the plugin manager as usually.

Next you can configure the plugin settings via the configuration manager (these settings are stored in conf/local.php) or you can save these protected against changes from the configuration manager by creating and editing the file conf/local.protected.php. Lastly, you change the authtype configuration to your new auth plugin and save. When your wiki becomes inaccessible again, you can modify the configuration settings via an editor on your server again.

See farther for more info about the configuration files and the config manager.

Old configurations

When auth plugin is activated, and there is an old config available, then first the old auth backend is loaded, next the new auth plugin config is loaded. So when auth plugin configuration settings are set these overwrite the old auth backend values.

Complete load sequence of plugin config settings:

  1. settings from lib/plugins/<pluginname>/conf/default.php
  2. settings from conf/local.php (or possibly overwritten by conf/local.protected.php) where:
    1. first settings of $config['auth']['<authbackendname>'] are read
    2. and next settings of $config['plugin']['auth<authbackendname>']

Tip:
When you start changing settings of auth plugin, especially when you reset a setting to its plugin default, it is recommended to remove the old $config['auth']['<authbackendname>'] settings from the local.php and/or local.protected.php.

Howto update your old backend

Some tips on updating your backend from inc/auth/<authname>.class.php to an Auth plugin.

Simple approach:

  1. Create a plugin skelet corresponding to plugin file structure and the synopsis at top of this page. (skelet generator: http://pluginwiz.dokuwiki.org/)
    • Please prefix the plugin name of your Auth plugin by auth e.g. authexample.
  2. You can reuse the code from inc/auth/<authbackendname>.class.php in your new lib/plugins/auth<authbackendname>/auth.php.
    • Be aware you can load other plugins or helper plugins
    • There are some inherited functions for localisation, configuration and more, see inherited methods above.

FIXME more relevant directions??

1)
définie dans lib/plugins/auth.php
fr/devel/auth_plugins.txt · Dernière modification: 2018-07-19 04:13 par schplurtz