Difference between revisions of "LDAP Authentication"

From WeBWorK_wiki
Jump to navigation Jump to search
(New page: = Using an LDAP server to authenticate WeBWorK users = WeBWorK 2.3 contains support for authenticating against an LDAP database. This is ready for use now, although configuration is manua...)
 
(Remove obsolete information)
 
(25 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
= Using an LDAP server to authenticate WeBWorK users =
  
  +
WeBWorK contains support for authenticating WeBWorK logins against an LDAP database. The WeBWorK LDAP authentication module supports vanilla LDAP as well as Bind accounts and Active Directory search.
   
−
WeBWorK 2.3 contains support for authenticating against an LDAP database. This is ready for use now, although configuration is manual at the moment and there are several limitations.
  
  +
== Configuring WeBWorK to use LDAP authentication ==
   
−
== Requirements ==
  
  +
LDAP authentication may be enabled for all WeBWorK courses on a server, or for individual courses on a server. The latter may be useful when a single WeBWorK installation is being used to host courses at multiple institutions.
   
−
WeBWorK 2.3.x or newer.
  
  +
=== Configuring LDAP for all courses ===
   
−
For WeBWorK 2.3.0, the <code>Net::LDAPS</code> Perl module and access to an LDAPS server.
  
  +
To use LDAP authentication for all courses on a WeBWorK server, in <code>webwork2/conf/authen_ldap.conf.dist</code> you must edit the <code>$authen{user_module}</code> hash to enable the LDAP authentication module and then edit the <code>$authen{ldap_options}</code> hash to configure the LDAP module for your specific environment. You may need to uncomment the line <code>include("conf/authen_ldap.conf");</code> in the <code>localOverrides.conf</code> file.
   
−
For later versions of WeBWorK, the <code>Net::LDAP</code> Perl module and access to an LDAP or LDAPS server.
  
  +
First, enable LDAP authentication by modifying <code>$authen{user_module}</code> in <code>authen_ldap.conf.dist</code> to read:
   
−
== Usage ==
  
  +
$authen{user_module} = {
  +
"*" => "WeBWorK::Authen::LDAP",
  +
};
   
−
If you are using WeBWorK 2.3.0, you'll have to set the following configuration options in <code>webwork2/lib/WeBWorK/Authen/LDAP.pm</code>:
  
  +
Next, configure LDAP authentication by modifying the <code>$authen{ldap_options}</code> hash in <code>authen_ldap.conf.dist</code>. The exact settings here are all site-specific. The items in this hash are as follows:
   
 
{| border="1"
  
{| border="1"
 
|-
  
|-
−
| '''constant''' || '''description'''
+
| '''key''' || '''description'''
 
|-
  
|-
−
| <code>$TIMEOUT</code> || Seconds to wait for LDAP server.
 
  +
| <code>net_ldap_hosts</code> || A reference to an array listing hosts to attempt to connect to. Examples:<br><small> <code>auth.myschool.edu</code> (uses LDAP scheme and port 389)<br> <code>ldap://auth.myschool.edu:666</code> (non-standard port)<br> <code>ldaps://auth.myschool.edu</code> (uses LDAPS scheme and port 636)<br> <code>ldaps://auth.myschool.edu:389</code> (SSL on non-SSL port)</small>
 
|-
  
|-
−
| <code>$PORT</code> || TCP port to connect to on LDAP server.
 
  +
| <code>net_ldap_options</code> || Options passed to Net::LDAP's constructor. See [http://search.cpan.org/~gbarr/perl-ldap/lib/Net/LDAP.pod#CONSTRUCTOR Net::LDAP#CONSTRUCTOR] for details.
 
|-
  
|-
−
| <code>$VERSION</code> || LDAP protocol version to use.
 
  +
| <code>net_ldap_base</code> || Tells the WeBWorK server which part of the external directory tree to search. This is site-specific and may be something equivalent to the organization, group, or domain name (AD) of external directory; e.g. <code>"ou=people,dc=myschool,dc=edu"</code>
 
|-
  
|-
−
| <code>$BASE</code> || LDAP base string.
 
  +
| <code>bindAccount</code> || Set <code>bindAccount = 1</code> to authenticate to LDAP server. Must set <code>searchDN</code> and <code>bindPassword</code>.
 
|-
  
|-
−
| <code>@HOST</code> || This is kind of confusing. This is a one-element array, containing an arrayref. The arrayref is a list of servers to attempt to connect to. You'll see what to do when you look at the file. (Yes, this is a bug.)
 
  +
| <code>searchDN</code> || For use when <code>bindAccount = 1</code>. The <code>searchDN</code> represents the user on the external LDAP server permitted to search the LDAP directory within the defined search base; e.g <code>searchDN = "cn=administrator,dc=myschool,dc=edu"</code>.
−  
−
|}
  
−  
−
If you are using 2.3.1 or later, the configuration process has changed somewhat. Rather than setting options in <code>LDAP.pm</code>, all configuration is now done in <code>global.conf</code>, using the <code>$authen{ldap_options}</code> hash. The items in this hash are as follows:
  
−  
−
{| border="1"
  
 
|-
  
|-
−
| '''key''' || '''description'''
 
  +
| <code>bindPassword</code> || Password for Bind user identified by <code>searchDN</code>. Note that in perl double quoted strings are interpolated, so expressions like <code>bindPassword = "pas$word";</code> and <code>bindPassword = "p@ssword";</code> should be replaced by <code>bindPassword = "pas\$word";</code> and <code>bindPassword = "p\@ssword";</code> or <code>bindPassword = 'pas$word';</code> and <code>bindPassword = 'p@ssword';</code>.
 
|-
  
|-
−
| <code>net_ldap_hosts</code> || A reference to an array listing hosts to attempt to connect to. Examples:<br><small> <code>auth.myschool.edu</code> (uses LDAP scheme and port 389)<br> <code>ldap://auth.myschool.edu:666</code> (non-standard port)<br> <code>ldaps://auth.myschool.edu</code> (uses LDAPS scheme and port 636)<br> <code>ldaps://auth.myschool.edu:389</code> (SSL on non-SSL port)</small>
 
  +
| <code>net_ldap_rdn</code> || The LDAP module searches for a DN whose RDN matches the username entered by the user. The <code>net_ldap_rdn</code> will depend on your LDAP setup. By default <code>net_ldap_rdn = "sAMAccountName</code> for use with Active Directory. If you schema uses UID as RDN set <code>net_ldap_rdn = "uid"</code>
 
|-
  
|-
−
| <code>net_ldap_options</code> || Options passed to Net::LDAP's constructor. See [http://search.cpan.org/~gbarr/perl-ldap/lib/Net/LDAP.pod#CONSTRUCTOR Net::LDAP#CONSTRUCTOR] for details.
 
  +
| <code>failover</code> || If <code>failover = "all"</code>, then LDAP failures will be checked against the WeBWorK database. If <code>failover = "local"</code>, then only users who don't exist in the LDAP database will be checked against the WeBWorK database. If <code>failover = 0</code>, then no attempts will be checked against the WeBWorK database. The setting <code>failover = 1</code> is equivalent to <code>failover="all"</code>.
−
|-
  
−
| <code>net_ldap_base</code> || LDAP base to use when searching for the user's DN. Site-specific.
 
−
|-
  
−
| <code>failover</code> || If this is true, the WeBWorK password database will be consulted if the LDAP server rejects the user's password. The is necessary if you want to allow users to log in who are not listed in the LDAP server's database.
 
−  
 
|}
  
|}
   
−
The following instructions apply both 2.3.0 and post-2.3.0 versions of WeBWorK.
  
  +
=== Configuring LDAP on a course-by-course basis ===
   
−
To use LDAP authentication with one course, add this to the course's <code>course.conf</code> file:
  
  +
Each course has a <code>course.conf</code> file in its root directory whose purpose is to override settings in <code>global.conf</code> with course-specific configuration parameters. Therefore, by adding the appropriate <code>$authen{user_module}</code> and <code>$authen{ldap_options}</code> hashes to <code>course.conf</code> one can override the global LDAP settings on the server.
−
<nowiki>
  
−
$authen{user_module}{"*"} = "WeBWorK::Authen::LDAP";
  
−
</nowiki>
  
−  
−
To use LDAP authentication with all courses, change the <code>$authen{user_module}</code> hash in <code>global.conf</code> to look like this:
  
−
<nowiki>
  
−
$authen{user_module} = {
  
−
sql_moodle => "WeBWorK::Authen::Moodle",
  
−
"*" => "WeBWorK::Authen::LDAP",
  
−
};
  
−
</nowiki>
  
   
 
== Security Considerations ==
  
== Security Considerations ==
Line 66: Line 46:
 
You must make sure that each accounts in your WeBWorK course "belongs" to the same person as the LDAP account with the same user ID. User ID mapping is not supported.
  
You must make sure that each accounts in your WeBWorK course "belongs" to the same person as the LDAP account with the same user ID. User ID mapping is not supported.
   
−
In WeBWorK 2.3.0, the LDAP module always fails over to checking the WeBWorK password if LDAP authentication fails.
 +
With <code>failover = "all"</code>, the LDAP module always fails over to checking the WeBWorK password if LDAP authentication fails.
  +
  +
It is suggested to run the authentication over SSL so that the password is encrypted and not sent in plain text.
   
 
== Limitations ==
  
== Limitations ==
   
−
The code is slanted towards University of Rochester's <nop>NetID implementation and hasn't been tested with other systems.
  
  +
Users must still be added to WeBWorK manually. The LDAP module itself does not do this for you.
−  
−
Only LDAPS is supported in WeBWorK 2.3.0. Both LDAP and LDAPS servers are supported in later versions.
  
−  
−
You still have to add users to WeBWorK manually.
  
   
 
Gateway test proctors cannot authenticate with LDAP. They will have to have valid passwords in the WeBWorK database.
  
Gateway test proctors cannot authenticate with LDAP. They will have to have valid passwords in the WeBWorK database.
   
−
== Credits ==
 +
== Forum Discussions ==
   
−
Mike Gage wrote the <nop>WeBWorK::Authen::LDAP module. He used sample code written by Christina Plummer of UR ITS.
  
  +
*[http://webwork.maa.org/moodle/mod/forum/discuss.php?d=2470 LDAP Search] 25 May 2011
  +
*[http://webwork.maa.org/moodle/mod/forum/discuss.php?d=2324 ldap failover not working] 9 Sept 2010
  +
*[http://webwork.maa.org/moodle/mod/forum/discuss.php?d=580 Authentication problems] 21 Dec 2009
  +
*[http://webwork.maa.org/moodle/mod/forum/discuss.php?d=199 LDAP credentials] 20 Mar 2009
   
−
-- Main.SamHathaway - 31 Aug 2006
  
  +
[[Category:Administrators]]
  +
[[Category:Authentication]]

Latest revision as of 17:07, 24 February 2025

WeBWorK contains support for authenticating WeBWorK logins against an LDAP database. The WeBWorK LDAP authentication module supports vanilla LDAP as well as Bind accounts and Active Directory search.

Configuring WeBWorK to use LDAP authentication

LDAP authentication may be enabled for all WeBWorK courses on a server, or for individual courses on a server. The latter may be useful when a single WeBWorK installation is being used to host courses at multiple institutions.

Configuring LDAP for all courses

To use LDAP authentication for all courses on a WeBWorK server, in webwork2/conf/authen_ldap.conf.dist you must edit the $authen{user_module} hash to enable the LDAP authentication module and then edit the $authen{ldap_options} hash to configure the LDAP module for your specific environment. You may need to uncomment the line include("conf/authen_ldap.conf"); in the localOverrides.conf file.

First, enable LDAP authentication by modifying $authen{user_module} in authen_ldap.conf.dist to read: 

$authen{user_module} = {
        "*" => "WeBWorK::Authen::LDAP",
};

Next, configure LDAP authentication by modifying the $authen{ldap_options} hash in authen_ldap.conf.dist. The exact settings here are all site-specific. The items in this hash are as follows:

key description
net_ldap_hosts A reference to an array listing hosts to attempt to connect to. Examples:
auth.myschool.edu (uses LDAP scheme and port 389)
ldap://auth.myschool.edu:666 (non-standard port)
ldaps://auth.myschool.edu (uses LDAPS scheme and port 636)
ldaps://auth.myschool.edu:389 (SSL on non-SSL port)
net_ldap_options Options passed to Net::LDAP's constructor. See Net::LDAP#CONSTRUCTOR for details.
net_ldap_base Tells the WeBWorK server which part of the external directory tree to search. This is site-specific and may be something equivalent to the organization, group, or domain name (AD) of external directory; e.g. "ou=people,dc=myschool,dc=edu"
bindAccount Set bindAccount = 1 to authenticate to LDAP server. Must set searchDN and bindPassword.
searchDN For use when bindAccount = 1. The searchDN represents the user on the external LDAP server permitted to search the LDAP directory within the defined search base; e.g searchDN = "cn=administrator,dc=myschool,dc=edu".
bindPassword Password for Bind user identified by searchDN. Note that in perl double quoted strings are interpolated, so expressions like bindPassword = "pas$word"; and bindPassword = "p@ssword"; should be replaced by bindPassword = "pas\$word"; and bindPassword = "p\@ssword"; or bindPassword = 'pas$word'; and bindPassword = 'p@ssword';.
net_ldap_rdn The LDAP module searches for a DN whose RDN matches the username entered by the user. The net_ldap_rdn will depend on your LDAP setup. By default net_ldap_rdn = "sAMAccountName for use with Active Directory. If you schema uses UID as RDN set net_ldap_rdn = "uid"
failover If failover = "all", then LDAP failures will be checked against the WeBWorK database. If failover = "local", then only users who don't exist in the LDAP database will be checked against the WeBWorK database. If failover = 0, then no attempts will be checked against the WeBWorK database. The setting failover = 1 is equivalent to failover="all".

Configuring LDAP on a course-by-course basis

Each course has a course.conf file in its root directory whose purpose is to override settings in global.conf with course-specific configuration parameters. Therefore, by adding the appropriate $authen{user_module} and $authen{ldap_options} hashes to course.conf one can override the global LDAP settings on the server.

Security Considerations

You must make sure that each accounts in your WeBWorK course "belongs" to the same person as the LDAP account with the same user ID. User ID mapping is not supported.

With failover = "all", the LDAP module always fails over to checking the WeBWorK password if LDAP authentication fails.

It is suggested to run the authentication over SSL so that the password is encrypted and not sent in plain text.

Limitations

Users must still be added to WeBWorK manually. The LDAP module itself does not do this for you.

Gateway test proctors cannot authenticate with LDAP. They will have to have valid passwords in the WeBWorK database.

Forum Discussions

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=LDAP_Authentication&oldid=24966"