From 2ddbf1703f9b813999073cc1c915d3e647be0d55 Mon Sep 17 00:00:00 2001 From: Christian Weiske Date: Thu, 26 May 2011 21:37:06 +0200 Subject: [PATCH] fix authentication docs and integrate them in index.rst --- doc/authentication.txt | 258 ++++++++++++++++++++++------------------- doc/index.rst | 2 + 2 files changed, 139 insertions(+), 121 deletions(-) diff --git a/doc/authentication.txt b/doc/authentication.txt index da49e5a..c3ccb47 100644 --- a/doc/authentication.txt +++ b/doc/authentication.txt @@ -1,3 +1,4 @@ +============================================ External authentication with SemanticScuttle ============================================ @@ -12,8 +13,8 @@ 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 [1]. -It does this by providing different "authentication containers" [2], +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 @@ -24,51 +25,58 @@ is offline - you won't, execpt you switch it off in the SemanticScuttle configuration. -[1] http://pear.php.net/package/Auth -[2] http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php +__ http://pear.php.net/package/Auth +__ http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php Basic configuration =================== -The default configuration file data/config.default.php has an own section +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 +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/ directory should look similar to that: :: - src/ - Auth.php - Auth/ - Anonymous.php - Container.php - Container/ + src/ + Auth.php + Auth/ + Anonymous.php + Container.php + Container/ + .. + SemanticScuttle/ + header.php .. - SemanticScuttle/ - header.php - .. -After that, modify your data/config.php file. The most important change -is to use - $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; +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. +``$authType = 'MDB2';`` + selects the authentication container. - $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. +``$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. @@ -77,53 +85,53 @@ Authentication examples General database authentification --------------------------------- -Here you also need the PEAR MDB2 package. -The "new_link" option is important! +Here you also need the PEAR `MDB2 package`_. +The "``new_link``" option is important! -config.php settings: --8<------------------ -$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', -); --8<------------------ +``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. +Here you also need the PEAR `MDB2 package`_. -config.php settings: --8<------------------ -$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', -); --8<------------------ +``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', + ); + +.. _MDB2 package: http://pear.php.net/package/MDB2 MediaWiki @@ -132,66 +140,74 @@ 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 +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 +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. +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); +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: --8<------------------ -$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); -} --8<------------------ +``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); + } + + +.. _MediaWiki: http://www.mediawiki.org/wiki/MediaWiki Active Directory / LDAP ----------------------- Here we authenticate against an active directory server. -config.php settings: --8<------------------ -$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'; --8<------------------ +``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'; + diff --git a/doc/index.rst b/doc/index.rst index a260642..1b8feea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,9 +17,11 @@ First reads Features ======== +- `Custom user authentication`__ - `SSL Client certificates`__ - Themes__ +__ authentication.html __ ssl-client-certificates.html __ themes.html