Actions

Authentication plugins: Difference between revisions

From LimeSurvey Manual

m (changed 2.05 to master for the links to github)
(21 intermediate revisions by 7 users not shown)
Line 1: Line 1:
An authentication plugin has some additional requirements over a regular plugin. Here we list the requirements.
This is an overview of the authentication plugins currently shipped with LimeSurvey. If you want to extend or develop your own authentication plugin, please see [[Authentication_plugin development]]


To make creating your own authentication plugin easier, you should extend the abstract [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/AuthPluginBase.php AuthPluginBase] class.
== Internal database ==
This plugin is the default and can not be disabled. It uses the built in LimeSurvey database. It is a fall-back mechanism so that you can always login to the installation when needed.


To get an idea of the possibilities, check out the three core authentication plugins (check their pages for more information about configuration options):
== LDAP ==
* [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/core/plugins/Authdb/Authdb.php Authdb] Database authentication - this is the default method for all new LimeSurvey installations.[[Core_plugins#Internal_database|info]]
By activating this plugin you can perform basic authentication against an LDAP server. Make sure your PHP configuration has LDAP support enabled.
* [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/core/plugins/Authwebserver/Authwebserver.php Authwebserver] Webserver authentication - This one skips the login form, and provides methods for user creation. [[Core_plugins#Webserver_authentication|info]]
* [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/core/plugins/AuthLDAP/AuthLDAP.php AuthLDAP] LDAP authentication - Adds a custom error message and relies on a user being present in the LimeSurvey database. [[Core_plugins#LDAP|info]]


There are 6 events you can subscribe to:
'''Enabling and configuring settings for plugin AuthLDAP v2.05+'''


== beforeLogin ==
Enable LDAP in PHP.INI.
This is called first, and can possibly disable the loginform, for example when webserver authentication is used and we trust on that. To do this, use ''$this->setAuthPlugin()''
Verify that [http://php.net/manual/en/function.phpinfo.php phpinfo.php] shows that LDAP is enabled.
The location of LimeSurvey's built-in phpinfo.php is: Upper Right Menu -- Configuration -- Settings -- Global Settings.  Then, below the table, you will have a link for "Show PHPInfo".


== newLoginForm ==
Go to LimeSurvey Plugin Manager.
Here you can add your own elements to the form. You should add your username/password elements, but could also add a domain selector or anything else you need. This will only be shown when the selected authentication method was chosen on the selector that is added when more then one plugin is present. When your authentication plugin does not need a form, and can not be selected as an option (like webserver authentication) you should not add a form element here.
<syntaxhighlight lang="php">
$this->getEvent()                  // Get the current event
    ->getContent($this)          // Get the content for this plugin
    ->addContent(CHtml::tag(      // And add some content to it
        'li',
        array(),
        "<label for='user'>"  . gT("Username") . "</label><input name='user' id='user' type='text' size='40' maxlength='40' value='' />"))
    ->addContent(CHtml::tag(
        'li',
        array(),
        "<label for='password'>"  . gT("Password") . "</label><input name='password' id='password' type='password' size='40' maxlength='40' value='' />"));
</syntaxhighlight>


== afterLoginFormSubmit ==
Configure LDAP plugin.
When the form for this plugin was submitted, this event is called. Here you can handle setting the values to the plugin. This event is also called when there was no form submitted and form display was canceled in the beforeLogin event.


== newUserSession ==
This is where the real authentication takes place. You should use $this->setAuthSuccess($oUser) for a successful attempt and provide a User object. If you fail to do so it will result in an authentication failure. If you need to provide a message about why the authentication failed, you can do so by using $this->setAuthFailure($code, $message) where code is any code other than 0. The code is not used at this moment. The message should be a message in English, localised using the available tools in the plugin api. See the general plugin documenation for more information about that topic.


== beforeLogout ==
=== Simple Example settings ===
This is fired before the user is destroyed and the session regenerated. This is the time for cleanup / logout in external systems if needed.
Ldap server e.g. ldap://ldap.mydomain.com: ldap://ldap.mydomain.com
Port number (default when omitted is 389):
LDAP version (LDAPv2 = 2), e.g. 3: 3
Username prefix cn= or uid=: cn=
Username suffix e.g. @mydomain.com or remaining part of ldap query: ,OU=people,DC=mydomain,DC=com
Create a LimeSurvey administrator with the same name as a AD(active directory) user account.
Log in using the AD credentials(username and password).


== afterLogout ==
=== Example settings AD2008 & 2.05+ ===
When the user is destroyed, you might want to redirect to a different page then currently defined. This is the right place to do so.
 
'''Settings working with Active Directory 2008 and 2.05+ (build 140520) with AuthLDAP plugin '''.
 
==== Authentication with LDAP and ''userPrincipalName'' attribute ====
 
'''Note''': Authentication with ''userPrincipalName'' attribute (ie: firstname.lastname@example.intra). Create a LimeSurvey user with the same name as a AD(active directory) user account :
 
''Username'': '''firstname.lastname@example.intra'''
 
''Email'': '''firstname.lastname@example.intra'''
 
''Full name'': '''Firstname LASTNAME'''
 
Then configure the plugin : ''Plugin Manager > LDAP > Configure''.
 
''Ldap server e.g. ldap://ldap.example.intra'': '''ldap://ldap.example.intra'''
 
''Port number (default when omitted is 389)'': '''389'''
 
''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''
 
''Username prefix cn= or uid=: cn='': '''empty'''
 
''Username suffix e.g. @example.intra or remaining part of ldap query'': '''empty'''
 
Log in using the AD credentials (username: '''firstname.lastname@example.intra''' and password).
 
==== Authentication with LDAP and ''sAMaccountName'' attribute ====
 
'''Note''': Authentication with ''sAMaccountName'' attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :
 
''Username'': '''firstname.lastname'''
 
''Email'': '''firstname.lastname@example.intra'''
 
''Full name'': '''Firstname LASTNAME'''
 
Then configure the plugin : ''Plugin Manager > LDAP > Configure''.
 
''Ldap server e.g. ldap://ldap.example.com'': '''ldap://ldap.example.intra'''
 
''Port number (default when omitted is 389)'': '''389'''
 
''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''
 
''Username prefix cn= or uid=: cn='': '''empty'''
 
''Username suffix e.g. @example.com or remaining part of ldap query'': '''@example.intra'''
 
Log in using the AD credentials (username: '''firstname.lastname''' and password).
 
==== Authentication with LDAPS and ''sAMaccountName'' attribute ====
 
'''Note''': Authentication with ''sAMaccountName'' attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :
 
''Username'': '''firstname.lastname'''
 
''Email'': '''firstname.lastname@example.intra'''
 
''Full name'': '''Firstname LASTNAME'''
 
Then configure the plugin : ''Plugin Manager > LDAP > Configure''.
 
''Ldap server e.g. ldap://ldap.example.com'': '''ldaps://ldap.example.intra'''
 
''Port number (default when omitted is 389)'': '''636'''
 
''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''
 
''Username prefix cn= or uid=: cn='': '''empty'''
 
''Username suffix e.g. @example.intra or remaining part of ldap query'': '''@example.intra'''
 
Log in using the AD credentials (username: '''firstname.lastname''' and password).
 
=== Example settings OpenLDAP & 2.05+ ===
 
'''Settings working with OpenLDAP and 2.05+ (git version Feb. 2015) with AuthLDAP plugin '''.
 
==== Authentication with LDAP and ''uid'' attribute ====
 
'''Note''': Authentication with ''uid'' attribute. Create a LimeSurvey user with the same name as a the LDAP user account.
 
Then configure the plugin : ''Plugin Manager > LDAP > Configure''.
 
* ''Ldap server e.g. ldap://ldap.mydomain.com'': '''ldap://ldap.mydomain.com'''
* ''Port number (default when omitted is 389)'': '''(389 or leave blank)'''
* ''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''
* ''Select true if referrals must be followed (use false for ActiveDirectory)'': '''(leave blank)'''
* ''Check to enable Start-TLS encryption When using LDAPv3'': '''False'''
* ''Select how to perform authentication'': '''Search and bind'''
* ''Attribute to compare to the given login can be uid, cn, mail, ...'': '''uid'''
* ''Base DN for the user search operation'': '''ou=people,dc=mydomain,dc=com'''
* ''Optional extra LDAP filter to be ANDed to the basic (searchuserattribute=username) filter. Don't forget the outmost enclosing parentheses'': '''(leave blank)'''
* ''Optional DN of the LDAP account used to search for the end-user's DN. An anonymous bind is performed if empty.'': '''cn=admin,dc=mydomain,dc=com'''
* ''Password of the LDAP account used to search for the end-user's DN if previoulsy set.'': '''password''' (appears!)
* ''Check to make default authentication method'': '''(as you wish)'''
 
Log in using the LDAP credentials (username: '''user''' and password).
 
==== Authentication with OpenLDAP, ''uid'' attribute, and group restriction [2.62+] ====
 
Some applications require a separate LDAP query (beyond the user search and bind to check password) to determine if the user has sufficient authorization. For example, let's assume that LDAP has a <code>Groups</code> OU that includes an entry identified by <code>cn=limeusers</code> and our policy is that for a user to be authorized to use LimeSurvey that entry must include an attribute of the form <code>memberUid=<i>username</i></code> where ''username'' is the username (uid) entered by the user attempting to login. To configure LDAP for that, set up basic ''uid'' authentication as above and then set the following additional (optional) parameters:
 
* ''Optional base DN for group restriction'': <code>ou=Groups,dc=mydomain,dc=com</code>
* ''Optional filter for group restriction'': <code>(&(cn=limeusers)(memberUid=$username))</code>
 
Note:
# <code>$username</code> is a magic value (in the context of the filter parameter) that is replaced by the username entered by the user when logging in.
# Although intended for testing group membership as above, this optional "group restriction" capability can be used to add any authorization check that can be expressed as a separate filtered search like this.
# Before specifying a group restriction this way, verify that basic LDAP authentication is working correctly.
# If either of the group restriction parameters is empty then the group restriction step will not be applied.
 
== Webserver authentication ==
 
This plugin leaves authentication to the webserver and reads the result from a configurable server setting. This method has been around for a while, and was configured from config.php. If you used this authentication, you should enable the plugin in the plugins menu and move your configuration from config.php to the plugin's settings. Feel free to contact the team via the bugtracker or irc-channel if it no longer functions the way it did before.


[[Category:Plugins]]
[[Category:Plugins]]

Revision as of 20:33, 14 August 2017

This is an overview of the authentication plugins currently shipped with LimeSurvey. If you want to extend or develop your own authentication plugin, please see Authentication_plugin development

Internal database

This plugin is the default and can not be disabled. It uses the built in LimeSurvey database. It is a fall-back mechanism so that you can always login to the installation when needed.

LDAP

By activating this plugin you can perform basic authentication against an LDAP server. Make sure your PHP configuration has LDAP support enabled.

Enabling and configuring settings for plugin AuthLDAP v2.05+

Enable LDAP in PHP.INI. Verify that phpinfo.php shows that LDAP is enabled. The location of LimeSurvey's built-in phpinfo.php is: Upper Right Menu -- Configuration -- Settings -- Global Settings. Then, below the table, you will have a link for "Show PHPInfo".

Go to LimeSurvey Plugin Manager.

Configure LDAP plugin.


Simple Example settings

Ldap server e.g. ldap://ldap.mydomain.com: ldap://ldap.mydomain.com Port number (default when omitted is 389): LDAP version (LDAPv2 = 2), e.g. 3: 3 Username prefix cn= or uid=: cn= Username suffix e.g. @mydomain.com or remaining part of ldap query: ,OU=people,DC=mydomain,DC=com Create a LimeSurvey administrator with the same name as a AD(active directory) user account. Log in using the AD credentials(username and password).

Example settings AD2008 & 2.05+

Settings working with Active Directory 2008 and 2.05+ (build 140520) with AuthLDAP plugin .

Authentication with LDAP and userPrincipalName attribute

Note: Authentication with userPrincipalName attribute (ie: firstname.lastname@example.intra). Create a LimeSurvey user with the same name as a AD(active directory) user account :

Username: firstname.lastname@example.intra

Email: firstname.lastname@example.intra

Full name: Firstname LASTNAME

Then configure the plugin : Plugin Manager > LDAP > Configure.

Ldap server e.g. ldap://ldap.example.intra: ldap://ldap.example.intra

Port number (default when omitted is 389): 389

LDAP version (LDAPv2 = 2), e.g. 3: LDAPv3

Username prefix cn= or uid=: cn=: empty

Username suffix e.g. @example.intra or remaining part of ldap query: empty

Log in using the AD credentials (username: firstname.lastname@example.intra and password).

Authentication with LDAP and sAMaccountName attribute

Note: Authentication with sAMaccountName attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :

Username: firstname.lastname

Email: firstname.lastname@example.intra

Full name: Firstname LASTNAME

Then configure the plugin : Plugin Manager > LDAP > Configure.

Ldap server e.g. ldap://ldap.example.com: ldap://ldap.example.intra

Port number (default when omitted is 389): 389

LDAP version (LDAPv2 = 2), e.g. 3: LDAPv3

Username prefix cn= or uid=: cn=: empty

Username suffix e.g. @example.com or remaining part of ldap query: @example.intra

Log in using the AD credentials (username: firstname.lastname and password).

Authentication with LDAPS and sAMaccountName attribute

Note: Authentication with sAMaccountName attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :

Username: firstname.lastname

Email: firstname.lastname@example.intra

Full name: Firstname LASTNAME

Then configure the plugin : Plugin Manager > LDAP > Configure.

Ldap server e.g. ldap://ldap.example.com: ldaps://ldap.example.intra

Port number (default when omitted is 389): 636

LDAP version (LDAPv2 = 2), e.g. 3: LDAPv3

Username prefix cn= or uid=: cn=: empty

Username suffix e.g. @example.intra or remaining part of ldap query: @example.intra

Log in using the AD credentials (username: firstname.lastname and password).

Example settings OpenLDAP & 2.05+

Settings working with OpenLDAP and 2.05+ (git version Feb. 2015) with AuthLDAP plugin .

Authentication with LDAP and uid attribute

Note: Authentication with uid attribute. Create a LimeSurvey user with the same name as a the LDAP user account.

Then configure the plugin : Plugin Manager > LDAP > Configure.

  • Ldap server e.g. ldap://ldap.mydomain.com: ldap://ldap.mydomain.com
  • Port number (default when omitted is 389): (389 or leave blank)
  • LDAP version (LDAPv2 = 2), e.g. 3: LDAPv3
  • Select true if referrals must be followed (use false for ActiveDirectory): (leave blank)
  • Check to enable Start-TLS encryption When using LDAPv3: False
  • Select how to perform authentication: Search and bind
  • Attribute to compare to the given login can be uid, cn, mail, ...: uid
  • Base DN for the user search operation: ou=people,dc=mydomain,dc=com
  • Optional extra LDAP filter to be ANDed to the basic (searchuserattribute=username) filter. Don't forget the outmost enclosing parentheses: (leave blank)
  • Optional DN of the LDAP account used to search for the end-user's DN. An anonymous bind is performed if empty.: cn=admin,dc=mydomain,dc=com
  • Password of the LDAP account used to search for the end-user's DN if previoulsy set.: password (appears!)
  • Check to make default authentication method: (as you wish)

Log in using the LDAP credentials (username: user and password).

Authentication with OpenLDAP, uid attribute, and group restriction [2.62+]

Some applications require a separate LDAP query (beyond the user search and bind to check password) to determine if the user has sufficient authorization. For example, let's assume that LDAP has a Groups OU that includes an entry identified by cn=limeusers and our policy is that for a user to be authorized to use LimeSurvey that entry must include an attribute of the form memberUid=username where username is the username (uid) entered by the user attempting to login. To configure LDAP for that, set up basic uid authentication as above and then set the following additional (optional) parameters:

  • Optional base DN for group restriction: ou=Groups,dc=mydomain,dc=com
  • Optional filter for group restriction: (&(cn=limeusers)(memberUid=$username))

Note:

  1. $username is a magic value (in the context of the filter parameter) that is replaced by the username entered by the user when logging in.
  2. Although intended for testing group membership as above, this optional "group restriction" capability can be used to add any authorization check that can be expressed as a separate filtered search like this.
  3. Before specifying a group restriction this way, verify that basic LDAP authentication is working correctly.
  4. If either of the group restriction parameters is empty then the group restriction step will not be applied.

Webserver authentication

This plugin leaves authentication to the webserver and reads the result from a configurable server setting. This method has been around for a while, and was configured from config.php. If you used this authentication, you should enable the plugin in the plugins menu and move your configuration from config.php to the plugin's settings. Feel free to contact the team via the bugtracker or irc-channel if it no longer functions the way it did before.

Retrieved from "http://manual.limesurvey.org/index.php?title=Authentication_plugins&oldid=76230"