MoodleDocs - Contribucions de l'usuari [ca]

Usuari:Alastair Hole

2013-02-22T12:34:19Z

Afhole:

Alastair Hole <a.f.hole@bath.ac.uk>

Senior Educational Software and Systems Developer

Learning and Teaching Enhancement Office

University of Bath

+44 (0)1225 383576

Usuari:Alastair Hole

2013-02-22T12:34:09Z

Afhole:

Alastair Hole <a.f.hole@bath.ac.uk>
Senior Educational Software and Systems Developer
Learning and Teaching Enhancement Office
University of Bath
+44 (0)1225 383576

Performance recommendations

2012-10-03T14:21:44Z

Afhole: /* PHP performance */

{{Performance}}
Moodle can be made to perform very well, at small usage levels or scaling up to many thousands of users. The factors involved in performance are basically the same as for any PHP-based database-driven system. When trying to optimize your server, try to focus on the factor which will make the most difference to the user. For example, if you have relatively more users browsing than accessing the database, look to improve the webserver performance.

==Obtain a baseline benchmark==

Before attempting any optimization, you should obtain a baseline benchmark of the component of the system you are trying to improve. For Linux try [http://lbs.sourceforge.net/ LBS] and for Windows use the Performance Monitor. Once you have quantitative data about how your system is performing currently, you'll be able to determine if the change you have made has had any real impact.

The overall aim of adjustments to improve performance is to use RAM (cacheing) and to reduce disk-based activity. It is especially important to try to eliminate swap file usage as much as you can. If your system starts swapping, this is a sign that you need more RAM.

The '''optimization order preference''' is usually: primary storage (more RAM), secondary storage (faster hard disks/improved hard disk configuration), processor (more and faster).

==Scalability==

Moodle's design (with clear separation of application layers) allows for strongly scalable setups. (Please check the list of [[Large installations|large Moodle installations]].)

Large sites usually separate the web server and database onto separate servers, although for smaller installations this is typically not necessary.

It is possible to load-balance a Moodle installation, for example by using more than one webserver. The separate webservers should query the same database and refer to the same filestore area, but otherwise the separation of the application layers is complete enough to make this kind of clustering feasible. Similarly, the database could be a cluster of servers (e.g. a MySQL cluster), but this is not an easy task and you should seek expert support, e.g. from a Moodle Partner.

===Server cluster===

Using Moodle forum discussions:

*[http://moodle.org/mod/forum/discuss.php?d=57202 Moodle clustering]
*[http://moodle.org/mod/forum/discuss.php?d=44470 Software load balancing]
*[http://moodle.org/mod/forum/discuss.php?d=49986 TCP load balancing]
*[http://moodle.org/mod/forum/discuss.php?d=88214 Installation for 3000 simultaneous users]

==Hardware configuration==
'''Note''': The fastest and most effective change that you can make to improve performance is to '''increase the amount of RAM on your web server''' - get as much as possible (e.g. 4GB or more). Increasing primary memory will reduce the need for processes to swap to disk and will enable your server to handle more users.
* Better performance is gained by obtaining the best '''processor capability''' you can, i.e. dual or dual core processors. A modern BIOS should allow you to enable hyperthreading, but check if this makes a difference to the overall performance of the processors by using a [http://en.wikipedia.org/wiki/Super_PI CPU benchmarking tool].
* If you can afford them, use '''SCSI hard disks''' instead of SATA drives. SATA drives will increase your system's CPU utilization, whereas SCSI drives have their own integrated processors and come into their own when you have multiple drives. If you must have SATA drives, check that your motherboard and the drives themselves support NCQ (Native Command Queuing).
* Purchase hard disks with a '''low seek time'''. This will improve the overall speed of your system, especially when accessing Moodle's reports.
* Size your '''swap file''' correctly. The general advice is to set it to 4 x physical RAM.
* Use a '''RAID disk system'''. Although there are many different RAID configurations you can create, the following generally works best:
** install a hardware RAID controller (if you can)
** the operating system and swap drive on one set of disks configured as RAID-1.
** Moodle, Web server and Database server on another set of disks configured as RAID-5.
* Use '''gigabit ethernet''' for improved latency and throughput. This is especially important when you have your webserver and database server separated out on different hosts.
* Check the settings on your '''network card'''. You may get an improvement in performance by increasing the use of buffers and transmit/receive descriptors (balance this with processor and memory overheads) and off-loading TCP checksum calculation onto the card instead of the OS.
* Read this [http://moodle.org/mod/forum/discuss.php?d=68579 Case Study] on a server stress test with 300 users.
* See this [http://elearning.sgu.ac.jp/doc/PT/ accompanying report] on network traffic and server loads.
* See the [[Moodle.org configuration]]
* Also see this SFSU presentation at Educause (using VMWare): [http://www.educause.edu/Resources/AnOpenSourceLMSforaMissionCrit/162843]

==Operating System==
* You can use [http://en.wikipedia.org/wiki/Linux Linux](recommended), Unix-based, Windows or Mac OS X for the server '''operating system'''. *nix operating systems generally require less memory than Mac OS X or Windows servers for doing the same task as the server is configured with just a shell interface. Additionally Linux does not have licensing fees attached, but can have a big learning curve if you're used to another operating system. If you have a large number of processors running SMP, you may also want to consider using a highly tuned OS such as [http://en.wikipedia.org/wiki/Solaris_Operating_Environment Solaris].
* Check your own OS and '''vendor specific instructions''' for optimization steps.
** For Linux look at the [http://linuxperf.sourceforge.net/ Linux Performance Team] site.
** For Linux investigate the hdparm command, e.g. hdparm -m16 -d1 can be used to enable read/write on multiple sectors and DMA. Mount disks with the async and noatime options.
** For Windows set the sever to be optimized for network applications (Control Panel, Network Connections, LAN connection, Properties, File & Printer Sharing for Microsoft Networks, Properties, Optimization). You can also search the [http://technet.microsoft.com/ Microsoft TechNet site] for optimization documents.

==Web server performance==

Installing [http://www.mozilla.com/en-US/ Firefox] and the [https://addons.mozilla.org/en-US/firefox/addon/1843 firebug] extension will allow you to watch the time it takes for each page component to load. Also, the [https://addons.mozilla.org/en-US/firefox/addon/5369 Yslow] extension will evaluate your page against Yahoo's [http://www.skrenta.com/2007/05/14_rules_for_fast_web_pages_by_1.html 14 rules], full text [http://developer.yahoo.com/performance/rules.html Best Practices for Speeding Up Your Web Site], <strike>([http://video.yahoo.com/video/play?vid=1040890 video])</strike> for fast loading websites.

===PHP performance===
* You are strongly recommended to use a '''PHP accelerator''' to ease CPU load, such as [http://pecl.php.net/apc APC], [http://www.php-accelerator.co.uk/ PHPA], [http://trac.lighttpd.net/xcache/ Xcache], [http://sourceforge.net/projects/wincache WinCache] or [http://eaccelerator.net/ eAccelerator]. (Take care to choose a PHP accelerator that is known to work well with your version of PHP and note that Turck MMCache is [http://turckmmcache.exeprod.com/TheManifestoEnglish no longer maintained] and can cause failures with PHP 5).
* Improvements in read/write performance can be improved by putting the cached PHP pages on a [[TMPFS]] filesystem - but remember that you'll lose the cache contents when there is a power failure or the server is rebooted.
* Performance of PHP is better when installed as an '''Apache/IIS6 ISAPI module''' (rather than a CGI). IIS 7.0/7.5 (Windows Server 2008/R2) users should choose a FastCGI installation for best performance.
* Also check the '''memory_limit''' in php.ini, reduce it to 16M for Moodle version earlier than 1.7 ([http://moodle.org/mod/forum/discuss.php?d=39656 See this forum discussion]). For Moodle 1.7 or later, it is recommended that the value of memory_limit should be 40M. As of [http://www.php.net/ChangeLog-5.php PHP 5.2.1] the default value for the memory_limit directive is 128M.
* Also see [[PHP_settings_by_Moodle_version]]

===Install HowTo===
* [http://2bits.com/articles/installing-php-apc-gnulinux-centos-5.html APC on CentOS 5.x (linux)]
* [http://fplanque.com/dev/linux/install-apc-php-cache-debian-lenny APC on Debian (linux)]
* [http://www.linuxtuts.net/211-installing-memcached-php5-memcache-module-debian-apache2.html MemCache module on Debian (Apache2 and PHP5) ]
* [http://noveckg.blogspot.com/2010/03/installing-memcached-on-centos-5x.html Installing Memcache on CentOS 5.x (linux)]
* [http://noveckg.blogspot.com/2010/02/installing-eaccelerator-cache-for-php.html Installing eAccelerator on CentOS 5.x (linux)]
* [https://docs.moodle.org/en/Installing_eAccelerator_In_Ubuntu_Server/ Installing eAccelerator on Ubuntu Server (linux)]

===Apache performance===
* If you are using Apache on a Windows server, use the build from [http://www.apachelounge.com Apache Lounge] which is reported to have [http://moodle.org/mod/forum/discuss.php?d=93358 performance and stability improvements] compared to the official Apache download. Note that this is an unofficial build, so may not keep up with official releases.
* Set the '''MaxClients''' directive correctly. Use this formula to help (which uses 80% of available memory to leave room for spare):
MaxClients = Total available memory * 80% / Max memory usage of apache process
:Memory usage of apache process is usually 10MB but Moodle can easily use up to 100MB per process, so a general rule of thumb is to divide your available memory in megabytes by 100 to get a conservative setting for MaxClients. You are quite likely to find yourself lowering the MaxClients from its default of 150 on a Moodle server. To get a more accurate estimate read the value from the shell command:
#ps -ylC httpd --sort:rss

:If you need to increase the value of '''MaxClients''' beyond 256, you will also need to set the '''ServerLimit''' directive.

:'''Warning''': Do not be tempted to set the value of MaxClients higher than your available memory as your server will consume more RAM than available and start to swap to disk.
* Consider reducing the '''number of modules''' that Apache loads in the httpd.conf file to the minumum necessary to reduce the memory needed.
* Use the '''latest version of Apache''' - Apache 2 has an improved memory model which reduces memory usage further.
* For Unix/Linux systems, consider lowering '''MaxRequestsPerChild''' in httpd.conf to as low as 20-30 (if you set it any lower the overhead of forking begins to outweigh the benefits).
* For a heavily loaded server, consider setting '''KeepAlive Off''' (do this only if your Moodle pages do not contain links to resources or uploaded images) or lowering the '''KeepAliveTimeout''' to between 2 and 5. The default is 15 (seconds) - the higher the value the more server processes will be kept waiting for possibly idle connections. A more accurate value for KeepAliveTimeout is obtained by observing how long it takes your users to download a page. After altering any of the KeepAlive variables, monitor your CPU utilization as there may be an additional overhead in initiating more worker processes/threads.
* As an alternative to using KeepAlive Off, consider setting-up a '''Reverse Proxy server''' infront of the Moodle server to cache HTML files with images. You can then return Apache to using keep-alives on the Moodle server.
* If you do not use a .htaccess file, set the '''AllowOverride''' variable to AllowOverride None to prevent .htaccess lookups.
* Set '''DirectoryIndex''' correctly so as to avoid content-negotiation. Here's an example from a production server:
DirectoryIndex index.php index.html index.htm
* Unless you are doing development work on the server, set '''ExtendedStatus Off''' and disable mod_info as well as mod_status.
* Leave '''HostnameLookups Off''' (as default) to reduce DNS latency.
* Consider reducing the value of '''TimeOut''' to between 30 to 60 (seconds).
* For the '''Options directive''', avoid Options Multiviews as this performs a directory scan. To reduce disk I/O further use
Options -Indexes FollowSymLinks
*'''Caching (unsupported)''' - ''Please note that this kind of caching may create major problems during upgrades.'' Apache can be told to make pages load a lot faster by specifying that the browser should cache some various page elements such as images and reuse them from local memory rather than ask for them again every time a page is requested. How to do this varies slightly between OSes but there are two basic steps:

# Install and enable mod_expires - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<IfModule mod_expires.c>
ExpiresActive On
ExpiresDefault "access plus 1 seconds"
ExpiresByType text/html "access plus 1 seconds"
ExpiresByType image/gif "access plus 1 week"
ExpiresByType image/jpeg "access plus 1 week"
ExpiresByType image/png "access plus 1 week"
ExpiresByType text/css "access plus 1 week"
ExpiresByType text/javascript "access plus 1 week"
ExpiresByType application/x-javascript "access plus 1 week"
ExpiresByType text/xml "access plus 1 seconds"
</IfModule>

The effect is to make everything stay in the cache except HTML and XML, which change dynamically. It's possible to gain a several hundred percent decrease in load times this way. Adjust the cache times according to how often your images etc change.

* Compression reduces response times by reducing the size of the HTTP response
# Install and enable mod_deflate - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<ifModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/plain text/xml
</ifmodule>

More info: [http://www.metaskills.net/blog/heuristics/sysadmin/how-to-control-browser-caching-with-apache-2 www.metaskills.net]

===IIS performance===
All alter this location in the registry:
HKLM\SYSTEM\CurrentControlSet\Services\Inetinfo\Parameters\
* The equivalent to KeepAliveTimeout is '''ListenBackLog''' (IIS - registry location is HKLM\ SYSTEM\ CurrentControlSet\ Services\ Inetinfo\ Parameters). Set this to between 2 to 5.
*Change the '''MemCacheSize''' value to adjust the amount of memory (Mb) that IIS will use for its file cache (50% of available memory by default).
*Change the '''MaxCachedFileSize''' to adjust the maximum size of a file cached in the file cache in bytes. Default is 262,144 (256K).
*Create a new DWORD called '''ObjectCacheTTL''' to change the length of time (in milliseconds) that objects in the cache are held in memory. Default is 30,000 milliseconds (30 seconds).

===Lighttpd, NginX and Cherokee performance===
You can increase server performance by using a '''light-weight''' webserver like [http://www.lighttpd.net/ lighttpd], [http://nginx.net/ nginx] or [http://www.cherokee-project.com/ cherokee] in combination with PHP in FastCGI-mode. Lighttpd was originally created as a proof-of-concept[http://www.lighttpd.net/story] to address the [http://www.kegel.com/c10k.html C10k problem] and while primarily recommended for memory-limited servers, its design origins and asynchronous-IO model make it a suitable and proven[http://blog.lighttpd.net/articles/2006/12/28/lighttpd-powers-5-alexa-top-250-sites] alternative HTTP server for high-load websites and web apps, including Moodle. See the [[lighttpd | MoodleDocs Lighttpd page]] for additional information, configuration example and links.

Alternatively, both [http://www.lighttpd.net/ lighttpd] and [http://nginx.net/ nginx] are capable of performing as a load-balancer and/or reverse-proxy to alleviate load on back-end servers[http://www.linuxjournal.com/article/10108], providing benefit without requiring an actual software change on existing servers.

Do note that these are likely to be the least tested server environments of all particularly if you are using advanced features such as web services and/or Moodle Networking. They are probably best considered for heavily used Moodle sites with relatively simple configurations.

==Database performance==

Moodle contains a script which will display some key database performance statistics from the [http://phplens.com/lens/adodb/docs-perf.htm ADOdb performance monitor]. Run the script in your browser as in the following example:

http://www.mymoodle.com/admin/dbperformance.php

Use the data displayed as a guide to tune and improve the performance of your database server.

===MySQL performance===

The following are MySQL specific settings which can be adjusted for better performance in your my.cnf (my.ini in Windows). The file contains a list of settings and their values. To see the current values use these commands
SHOW STATUS;
SHOW VARIABLES;
'''Important''': You must make backups of your database before attempting to change any MySQL server configuration. After any change to the my.cnf, restart mysqld.

If you are able, the [http://mysqltuner.com/ MySQLTuner] tool can be run against your MySQL server and will calculate appropriate configuration values for most of the following settings based on your current load, status and variables automatically.

* Enable the '''query cache''' with
query_cache_type = 1.
For most Moodle installs, set the following:
query_cache_size = 36M
query_cache_min_res_unit = 2K.
The query cache will improve performance if you are doing few updates on the database.
* Set the '''table cache''' correctly. For Moodle 1.6 set
table_cache = 256 #(table_open_cache in MySQL > 5.1.2)
(min), and for Moodle 1.7 set
table_cache = 512 #(table_open_cache in MySQL > 5.1.2)
(min). The table cache is used by all threads (connections), so monitor the value of opened_tables to further adjust - if opened_tables > 3 * table_cache(table_open_cache in MySQL > 5.1.2) then increase table_cache upto your OS limit. Note also that the figure for table_cache will also change depending on the number of modules and plugins you have installed. Find the number for your server by executing the mysql statement below. Look at the number returned and set table_cache to this value.
mysql>SELECT COUNT(table_name) FROM information_schema.tables WHERE table_schema='yourmoodledbname';
* Set the '''thread cache''' correctly. Adjust the value so that your thread cache utilization is as close to 100% as possible by this formula:
thread cache utilization (%) = (threads_created / connections) * 100
* The '''key buffer''' can improve the access speed to Moodle's SELECT queries. The correct size depends on the size of the index files (.myi) and in Moodle 1.6 or later (without any additional modules and plugins), the recommendation for this value is key_buffer_size = 32M. Ideally you want the database to be reading once from the disk for every 100 requests so monitor that the value is suitable for your install by adjusting the value of key_buffer_size so that the following formulas are true:
key_read / key_read_requests < 0.01
key_write / key_write_requests <= 1.0
* Set the '''maximum number of connections''' so that your users will not see a "Too many connections" message. Be careful that this may have an impact on the total memory used. MySQL connections usually last for milliseconds, so it is unusual even for a heavily loaded server for this value to be over 200.
* Manage '''high burst activity'''. If your Moodle install uses a lot of quizzes and you are experiencing performance problems (check by monitoring the value of threads_connected - it should not be rising) consider increasing the value of back_log.
* '''Optimize your tables weekly and after upgrading Moodle'''. It is good practice to also optimize your tables after performing a large data deletion exercise, e.g. at the end of your semester or academic year. This will ensure that index files are up to date. Backup your database first and then use:
mysql>CHECK TABLE mdl_tablename;
mysql>OPTIMIZE TABLE mdl_tablename;
:The common tables in Moodle to check are mdl_course_sections, mdl_forum_posts, mdl_log and mdl_sessions (if using dbsessions). Any errors need to be corrected using REPAIR TABLE (see the [http://dev.mysql.com/doc/refman/5.0/en/repair-table.html MySQL manual] and this [http://moodle.org/mod/forum/discuss.php?d=58208#p279638 forum script]).
* '''Maintain the key distribution'''. Every month or so it is a good idea to stop the mysql server and run these myisamchk commands.
#myisamchk -a -S /pathtomysql/data/moodledir/*.MYI
:'''Warning''': You must stop the mysql database process (mysqld) before running any myisamchk command. If you do not, you risk data loss.
* Reduce the number of '''temporary tables saved to disk'''. Check this with the created_tmp_disk_tables value. If this is relatively large (>5%) increase tmp_table_size until you see a reduction. Note that this will have an impact on RAM usage.

===PostgreSQL performance===

There are some good papers around on tuning PostgreSQL (like [http://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server this one]), and Moodle's case does not seem to be different to the general case.

The first thing to recognise is that if you really need to worry about tuning you should be using a separate machine for the database server. If you are not using a separate machine then the answers to many performance questions are substantially muddied by the memory requirements of the rest of the application.

You should probably '''enable autovacuum''', unless you know what you are doing. Many e-learning sites have predictable periods of low use, so disabling autovacuum and running a specific vacuum at those times can be a good option. Or perhaps leave autovacuum running but do a full vacuum weekly in a quiet period.

Set '''shared_buffers''' to something reasonable. For versions up to 8.1 my testing has shown that peak performance is almost always obtained with buffers < 10000, so if you are using such a version, and have more than 512M of RAM just set shared_buffers to 10,000 (8MB).

The buffer management had a big overhaul in 8.2 and "reasonable" is now a much larger number. I have not conducted performance tests with 8.2, but the recommendations from others are generally that you should now scale shared_buffers much more with memory and may continue to reap benefits even up to values like 100,000 (80MB). Consider using 1-2% of system RAM.

PostgreSQL will also assume that the operating system is caching its files, so setting '''effective_cache_size''' to a reasonable value is also a good idea. A reasonable value will usually be (total RAM - RAM in use by programs). If you are running Linux and leave the system running for a day or two you can look at 'free' and under the 'cached' column you will see what it currently is. Consider taking that number (which is kB) and dividing it by 10 (i.e. allow 20% for other programs cache needs and then divide by 8 to get pages). If you are not using a dedicated database server you will need to decrease that value to account for usage by other programs.

Some other useful parameters that can have positive effects, and the values I would typically set them to on a machine with 4G RAM, are:

work_mem = 10240

That's 10M of RAM to use instead of on-disk sorting and so forth. That can give a big speed increase, but it is per connection and 200 connections * 10M is 2G, so it can theoretically chew up a lot of RAM.

maintenance_work_mem = 163840

That's 160M of RAM which will be used by (e.g.) VACUUM, index rebuild, cluster and so forth. This should only be used periodically and should be freed when those processes exit, so I believe it is well worth while.

max_fsm_pages = 100000
max_fsm_relations = 5000

These are used to hold the free-space map, and if they are too small you will see performance degradation after the database has been operating for some time. The exact numbers to set can be gleaned from the output of VACUUM VERBOSE, which prints the required FSM pages at the end of it's run. The 5x increase seems to be useful for a Moodle installation, from experience.

wal_buffers = 64

These buffers are used for the write-ahead log, and there have been a number of reports on the PostgreSQL mailing lists of improvement from this level of increase.

This is a little out of date now (version 8.0) but still worth a read: http://www.powerpostgresql.com/Docs

And there is lots of good stuff here as well: http://www.varlena.com/GeneralBits/Tidbits/index.php

''Based on Andrew McMillan's post at [http://moodle.org/mod/forum/discuss.php?d=68558 Tuning PostgreSQL] forum thread.''

===Other database performance links===
* Consider using a '''distributed cacheing system''' like [http://en.wikipedia.org/wiki/Memcached memcached] but note that memcached does not have any security features so it should be used behind a firewall.
* Consider using PostgreSQL. See [[Arguments in favour of PostgreSQL]] and [http://moodle.org/mod/forum/discuss.php?d=49195 how to migrate from MySQL to PostgreSQL] (forum discussion).
* [[Increasing the database connection lifetime | Try increasing the database connection lifetime]]
* [http://dev.mysql.com/doc/refman/5.0/en/server-parameters.html General advice on tuning MySQL parameters] (advice from the MySQL manual)
* [http://www.mysqlperformanceblog.com/2007/11/01/innodb-performance-optimization-basics/ InnoDB performance optimization] taken from the [http://www.mysqlperformanceblog.com/ MySQL performance blog] site.

==Performance of different Moodle modules==

Moodle's activity modules, filters, and other plugins can be activated/deactivated. If necessary, you may wish to deactivate some features (such as chat) if not required - but this isn't necessary. Some notes on the performance of certain modules:

* The '''Chat''' module is [http://moodle.org/mod/forum/discuss.php?d=37979&parent=175079 said] to be a hog in terms of frequent HTTP requests to the main server. This can be reduced by setting the module to use ''Streamed'' updates, or, if you're using a Unix-based webserver, by running the chat in daemon mode. When using the Chat module use the configuration settings to tune for your expected load. Pay particular attention to the ''chat_old_ping'' and ''chat_refresh'' parameters as these can have greatest impact on server load.
* The '''Quiz''' module is known to stretch database performance. Try to optimise your database server by tuning. See [http://moodle.org/mod/forum/discuss.php?d=25616&parent=120770 for a brief report on performance for 55 students simultaneously using quizzes]
** See this Case Study for an extensive server stress test with 300 quiz users.[http://moodle.org/mod/forum/discuss.php?d=68579] And this accompanying report on network traffic and server loads. [http://elearning.sgu.ac.jp/doc/PT/]
* The Moodle '''Cron''' task is triggered by calling the script ''cron.php''. If this is called over HTTP (e.g. using wget or curl) it can take a large amount of memory on large installations. If it is called by directly invoking the php command (e.g. ''php -f /path/to/moodle/directory/admin/cron.php'') efficiency can be much improved.
* The '''Recent activities''' block is consuming to much resources if you have huge number of records <code>mdl_log</code>. this is being tested to optimize the SQL query.

==Moodle Image Optimization==

The base images delivered in the original Moodle distribution package provide unoptimized graphics, most of which can benefit from lossless recompression utilizing [http://optipng.sourceforge.net/ optipng] for PNGs, [http://www.lcdf.org/gifsicle/ gifsicle] for GIFs and [http://www.kokkonen.net/tjko/projects.html jpegoptim] for JPGs. Optimized graphics transfer faster and provide a faster perceived response for clients[http://www.websiteoptimization.com/speed/12/], especially distance learners. The following example will recursively optimize (without any loss of quality) all the graphics and image files included in a base Moodle installation directory on a server with the above commands installed and available.

<pre>
find /example/directory/moodle-1.9 -iname *.png -exec optipng -o7 {} \;
find /example/directory/moodle-1.9 -iname *.gif -exec gifsicle -O2 -b {} \;
find /example/directory/moodle-1.9 -iname *.jpg -exec jpegoptim -p {} \;
</pre>

Both [http://optipng.sourceforge.net/ optipng] and [http://www.lcdf.org/gifsicle/ gifsicle] are provided in the base repositories of most newer Linux distributions; [http://www.kokkonen.net/tjko/projects.html jpegoptim] must be downloaded and installed manually.

==See also==

*Using Moodle: [http://moodle.org/mod/forum/view.php?f=94 Hardware and Performance] forum

There have been a lot of discussions on moodle.org about performance, here are some of the more interesting and (potentially) useful ones:

* [http://moodle.org/mod/forum/discuss.php?d=83057 Performance woes!]
* [http://moodle.org/mod/forum/discuss.php?d=57028 Performance perspectives - a little script]
* [http://moodle.org/mod/forum/discuss.php?d=88927 Comments on planned server hardware]
* [http://moodle.org/mod/forum/discuss.php?d=102978#p461624 Moodle performance in a pil by Martin Langhoff]

[[es:Rendimiento]]
[[fr:Performance]]
[[ja:パフォーマンス]]
[[de:Geschwindigkeitsempfehlungen]]

Broken/JavaScript guidelines

2010-08-16T19:41:14Z

Afhole:

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Usuari:Alastair Hole

2010-08-01T17:42:07Z

Afhole:

I'm a Web Developer working for [http://www.wortech.ac.uk/ Worcester College of Technology], developing and supporting the college's Moodle implementation.

I have also been involved in some plugin development, chiefly the [http://www.mrcute.co.uk/ MrCUTE repository]

Usuari:Alastair Hole

2010-08-01T17:41:26Z

Afhole:

I'm a Web Developer working for Worcester College of Technology, developing and supporting the college's Moodle implementation.

I have also been involved in some plugin development, chiefly the [http://www.mrcute.co.uk MrCUTE repository]

Usuari:Alastair Hole

2010-08-01T17:41:12Z

Afhole:

Usuari:Alastair Hole

2010-08-01T17:38:46Z

Afhole: New page: Author of MrCUTE Repository http://www.mrcute.co.uk

Author of MrCUTE Repository http://www.mrcute.co.uk

Broken/id:9232

2010-06-13T17:47:35Z

Afhole: /* Getting Moodle to load your JavaScript files */

== event handlers ==
Should there be a recommendation to use YUI event handlers instead of JavaScript's inline event handlers? This might be better for cross-browser compatibility. --[[User:Frank Ralf|Frank Ralf]] 09:24, 15 June 2009 (UTC)

:Good idea--[[User:Tim Hunt|Tim Hunt]] 03:16, 16 June 2009 (UTC)

== Getting Moodle to load your JavaScript files ==
are in_head and asap now obsolete?
It seems in_head is replaced by the second parameter to the js class constructor, is there an alternative for asap? --[[User:Alastair Hole|Alastair Hole]] 17:46, 13 June 2010 (UTC)

Broken/id:9232

2010-06-13T17:46:57Z

Afhole: /* Getting Moodle to load your JavaScript files */

== event handlers ==
Should there be a recommendation to use YUI event handlers instead of JavaScript's inline event handlers? This might be better for cross-browser compatibility. --[[User:Frank Ralf|Frank Ralf]] 09:24, 15 June 2009 (UTC)

:Good idea--[[User:Tim Hunt|Tim Hunt]] 03:16, 16 June 2009 (UTC)

== Getting Moodle to load your JavaScript files ==
are in_head and asap now obsolete?
It seems in_head is replaced by the second parameter to the js class, is there an alternative for asap? --[[User:Alastair Hole|Alastair Hole]] 17:46, 13 June 2010 (UTC)

Broken/id:9232

2010-06-13T17:46:17Z

Afhole: /* event handlers */

File upload size

2010-04-26T11:04:27Z

Afhole: /* Modifying the IIS 7.0/7.5 configuration (Windows Server 2008, Windows Server 2008 R2) */

Probably the most frequently asked question in the Moodle.org Using Moodle forums is "How do I increase the upload file size limit?" The changes that need be made are the same in all versions of Moodle, just in different OS' they need be made in different places. Upload file sizes are restricted in a number of ways and each one in this list restricts the following ones:

Server level
Moodle site level
Course level
Activity level

This is a contentious issue, mainly because you might think that it should be set inside the Moodle. Unfortunately, this is not so, these are environment issues that need to be set in the server and PHP folders, Moodle cannot work outside itself.

==Physical access to Server==
These instructions assume you have full physical and administrative access to your server. If you are using a hosted server then you will probably need to look into other ways to increase your file upload size.

There are positives and negatives to both methods below. If you modify the pnp.ini file then the changes will effect all php applications on your server. Since PHP5 you can only have one php.ini file on your server. The php.ini method will work with all web servers though. The .htaccess method will only effect the folder and all subfolders that it is placed in, but you must have certain settings enabled in Apache.

===Modifying the php.ini file===
These instructions show you how to change the file upload size by editing your php.ini file.
====Ubuntu Linux Instructions====

These instructions assume that you have installed the standard Moodle package, PHP 5 and Apache 2 via apt-get and left it all as a default install. If you have compiled yourself I presume that you will know where your php.ini files are!

You need to edit the following three settings in your php.ini file located at: /etc/php5/apache2/

*Type "sudo nano /etc/php5/apache2/php.ini"
*Press Ctrl and W and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "max_execution_time"
*Change the value to 600
*Press Ctrl and O
*Press Ctrl and X
*Type sudo /etc/init.d/apache2 restart

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

====Windows XP and Server 2003 Instructions====

These instructions presume that you have downloaded the latest PHP 5.2.x Windows zip package and extracted it to C:\PHP. If you have installed PHP to another location then change all references to "C:\PHP" to the location you installed PHP too.

*Open C:\PHP
*Right Click the '''php.ini''' file in this folder and choose "Open with..."
*Choose "Wordpad" not "Notepad" to open the file with (Notepad does not properly use the UTF-8 Character set and it's carriage returns can cause problems)
**Better still download and install any text editor that can save the file in a UTF-8 format, [http://www.crimsoneditor.com Crimson Editor] is one such, and use that instead of either Wordpad or Notepad!
*Press Ctrl and F and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "max_execution_time"
*Change the value to 600
*Press Ctrl and S
*Exit Wordpad
*Restart your webserver
**'''For IIS'''
**Open your Start Menu on your server and select "Run"
**Type "iisreset /RESTART"
**'''For Apache 2'''
**The following command will work as long as you have installed Apache 2 as a service on your Windows Server
**Open your Start Menu on your server and select "Run"
**Type "httpd -k restart"

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

'''NOTE:''' These instructions should also cover the Xampp Windows installer. Just replace C:\PHP with C:\Moodle\server\php and to restart your Moode with a normal stop-start.

===Modifying the apache config file===
====Ubuntu Linux Instructions====
You may also need to edit the config.php file in the moodle directory:
*Type "gksudo nautilus" to get root permissions
*Navigate to /etc/moodle
*Open apache.conf
*Go to the "<IfModule mod_php5.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Go to the "<IfModule mod_php4.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Save file
*Type sudo /etc/init.d/apache2 restart

===Modifying the .htaccess file===
{{stub}}
The following instructions will only work on an Apache web server, and also the Apache server must have Overrides allowed. Additionally php must be running as an apache module, not as a cgi program.

Create a file called .htaccess in Moodle's main directory (where 'index.php' is located, not the 'moodledata' directory) that contains the following information:

php_value upload_max_filesize 20971520
php_value post_max_size 20971520
php_value max_execution_time 600

20971520 is the integer value for 20Mb. You can use the following site to [http://www.onlineconversion.com/computer_base2.htm convert MegaBytes to Bytes].

===Modifying the IIS 7.0/7.5 configuration (Windows Server 2008, Windows Server 2008 R2)===
First increase activity and request time outs (allows large files to succeed on slow connections)
FastCGI Settings > Edit (Right-click on PHP application)
Set Process Model > Activity Timeout to '3600' (one hour)
Set Process Model > Request Timeout to '3600' (one hour)
Next set 'Maximum allowed content length'
Request Filtering > Edit Feature Settings:
Set 'Maximum allowed content length' to your desired file size (in bytes) e.g. '536870912' for 512MB (default is approximately 28.6MB)

==Hosted Server==
Things can be a little different with a hosted server for uploaded and downloaded file size. You are probably going to to be told to create or change a .htaccess file, or to modify a php.ini file.

:It might be a good idea to talk to with your service provider before you attempt anything. They probably have instructions on "how to" and may have their own limits for uploaded file size. Some hosts measure the file size in gigabytes and others in megabytes. If you are unhappy with their limits, then check your contract and consider changing your provider to one that has a limit and price that you like.

===.htaccess with hosted server===
The one purpose of an .htaccess file is to override the the current limitations of both the server and the php.ini file. Your hosted server should inform you where that file needs be placed in your Moodle, but generally in the root is sufficient. They may already have a standard file you can use, if so, use it - but perhaps not.

To the .htaccess file add the lines:
php_value upload_max_filesize 128M
php_value post_max_size 128M

This will limit uploads to 128MB, but you can make it any size you agree with your provider. The wording may vary slightly, according to the demands of the server.

===php.ini with hosted server===
Some servers will not allow you to change the moodle root .htaccess file and tell you to use a php.ini file for php directives. Here you can use the instruction located in the section above called [[File_upload_size#Modifying_the_php.ini_file|Modifying the php.ini file]].

Find the php.ini file in your moodle subfolder on your hosted server. You might want to copy the file as a backup just in case. Edit php.ini, find "upload_max_filesize" and post_max_size in the code. After the = change the number. Here the max filesize is 20 megabytes.

upload_max_filesize = 20M
post_max_size = 20M

:Tip: Still not changed? Some hosts using cpanel have a php config program under services/software. Use the "Single php.ini" option and make sure you note the location of the php.ini file to modify. This changes the .htaccess file in the same area and thus the server limit for all programs using php.

==See Also==
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F|Administration FAQ Doc page]]
*[[Site_policies#Maximum_uploaded_file_size|Site Policies Doc page]]
*[[Installing_Moodle/Creating_custom_php.ini_files|Creating custom php.ini files Doc Page]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=39625 Detailed instructions to increase the maximum allowed size for uploaded files] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97907 Instructions to increase maximum allowed size on hosted servers] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=124441 Help on changing the maximum upload size when installing Moodle via apt-get] forum discussion

[[Category:Administrator|File]][[Category:FAQ|File]]

File upload size

2010-04-26T11:04:03Z

Afhole:

Probably the most frequently asked question in the Moodle.org Using Moodle forums is "How do I increase the upload file size limit?" The changes that need be made are the same in all versions of Moodle, just in different OS' they need be made in different places. Upload file sizes are restricted in a number of ways and each one in this list restricts the following ones:

Server level
Moodle site level
Course level
Activity level

This is a contentious issue, mainly because you might think that it should be set inside the Moodle. Unfortunately, this is not so, these are environment issues that need to be set in the server and PHP folders, Moodle cannot work outside itself.

==Physical access to Server==
These instructions assume you have full physical and administrative access to your server. If you are using a hosted server then you will probably need to look into other ways to increase your file upload size.

There are positives and negatives to both methods below. If you modify the pnp.ini file then the changes will effect all php applications on your server. Since PHP5 you can only have one php.ini file on your server. The php.ini method will work with all web servers though. The .htaccess method will only effect the folder and all subfolders that it is placed in, but you must have certain settings enabled in Apache.

===Modifying the php.ini file===
These instructions show you how to change the file upload size by editing your php.ini file.
====Ubuntu Linux Instructions====

These instructions assume that you have installed the standard Moodle package, PHP 5 and Apache 2 via apt-get and left it all as a default install. If you have compiled yourself I presume that you will know where your php.ini files are!

You need to edit the following three settings in your php.ini file located at: /etc/php5/apache2/

*Type "sudo nano /etc/php5/apache2/php.ini"
*Press Ctrl and W and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "max_execution_time"
*Change the value to 600
*Press Ctrl and O
*Press Ctrl and X
*Type sudo /etc/init.d/apache2 restart

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

====Windows XP and Server 2003 Instructions====

These instructions presume that you have downloaded the latest PHP 5.2.x Windows zip package and extracted it to C:\PHP. If you have installed PHP to another location then change all references to "C:\PHP" to the location you installed PHP too.

*Open C:\PHP
*Right Click the '''php.ini''' file in this folder and choose "Open with..."
*Choose "Wordpad" not "Notepad" to open the file with (Notepad does not properly use the UTF-8 Character set and it's carriage returns can cause problems)
**Better still download and install any text editor that can save the file in a UTF-8 format, [http://www.crimsoneditor.com Crimson Editor] is one such, and use that instead of either Wordpad or Notepad!
*Press Ctrl and F and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "max_execution_time"
*Change the value to 600
*Press Ctrl and S
*Exit Wordpad
*Restart your webserver
**'''For IIS'''
**Open your Start Menu on your server and select "Run"
**Type "iisreset /RESTART"
**'''For Apache 2'''
**The following command will work as long as you have installed Apache 2 as a service on your Windows Server
**Open your Start Menu on your server and select "Run"
**Type "httpd -k restart"

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

'''NOTE:''' These instructions should also cover the Xampp Windows installer. Just replace C:\PHP with C:\Moodle\server\php and to restart your Moode with a normal stop-start.

===Modifying the apache config file===
====Ubuntu Linux Instructions====
You may also need to edit the config.php file in the moodle directory:
*Type "gksudo nautilus" to get root permissions
*Navigate to /etc/moodle
*Open apache.conf
*Go to the "<IfModule mod_php5.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Go to the "<IfModule mod_php4.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Save file
*Type sudo /etc/init.d/apache2 restart

===Modifying the .htaccess file===
{{stub}}
The following instructions will only work on an Apache web server, and also the Apache server must have Overrides allowed. Additionally php must be running as an apache module, not as a cgi program.

Create a file called .htaccess in Moodle's main directory (where 'index.php' is located, not the 'moodledata' directory) that contains the following information:

php_value upload_max_filesize 20971520
php_value post_max_size 20971520
php_value max_execution_time 600

20971520 is the integer value for 20Mb. You can use the following site to [http://www.onlineconversion.com/computer_base2.htm convert MegaBytes to Bytes].

===Modifying the IIS 7.0/7.5 configuration (Windows Server 2008, Windows Server 2008 R2)===
First increase activity and request time outs (allows large files to succeed on slow connections)
FastCGI Settings > Edit (Right-click on PHP application
Set Process Model > Activity Timeout to '3600' (one hour)
Set Process Model > Request Timeout to '3600' (one hour)
Next set 'Maximum allowed content length'
Request Filtering > Edit Feature Settings:
Set 'Maximum allowed content length' to your desired file size (in bytes) e.g. '536870912' for 512MB (default is approximately 28.6MB)

==Hosted Server==
Things can be a little different with a hosted server for uploaded and downloaded file size. You are probably going to to be told to create or change a .htaccess file, or to modify a php.ini file.

:It might be a good idea to talk to with your service provider before you attempt anything. They probably have instructions on "how to" and may have their own limits for uploaded file size. Some hosts measure the file size in gigabytes and others in megabytes. If you are unhappy with their limits, then check your contract and consider changing your provider to one that has a limit and price that you like.

===.htaccess with hosted server===
The one purpose of an .htaccess file is to override the the current limitations of both the server and the php.ini file. Your hosted server should inform you where that file needs be placed in your Moodle, but generally in the root is sufficient. They may already have a standard file you can use, if so, use it - but perhaps not.

To the .htaccess file add the lines:
php_value upload_max_filesize 128M
php_value post_max_size 128M

This will limit uploads to 128MB, but you can make it any size you agree with your provider. The wording may vary slightly, according to the demands of the server.

===php.ini with hosted server===
Some servers will not allow you to change the moodle root .htaccess file and tell you to use a php.ini file for php directives. Here you can use the instruction located in the section above called [[File_upload_size#Modifying_the_php.ini_file|Modifying the php.ini file]].

Find the php.ini file in your moodle subfolder on your hosted server. You might want to copy the file as a backup just in case. Edit php.ini, find "upload_max_filesize" and post_max_size in the code. After the = change the number. Here the max filesize is 20 megabytes.

upload_max_filesize = 20M
post_max_size = 20M

:Tip: Still not changed? Some hosts using cpanel have a php config program under services/software. Use the "Single php.ini" option and make sure you note the location of the php.ini file to modify. This changes the .htaccess file in the same area and thus the server limit for all programs using php.

==See Also==
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F|Administration FAQ Doc page]]
*[[Site_policies#Maximum_uploaded_file_size|Site Policies Doc page]]
*[[Installing_Moodle/Creating_custom_php.ini_files|Creating custom php.ini files Doc Page]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=39625 Detailed instructions to increase the maximum allowed size for uploaded files] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97907 Instructions to increase maximum allowed size on hosted servers] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=124441 Help on changing the maximum upload size when installing Moodle via apt-get] forum discussion

[[Category:Administrator|File]][[Category:FAQ|File]]

File upload size

2010-04-26T11:03:06Z

Afhole:

Probably the most frequently asked question in the Moodle.org Using Moodle forums is "How do I increase the upload file size limit?" The changes that need be made are the same in all versions of Moodle, just in different OS' they need be made in different places. Upload file sizes are restricted in a number of ways and each one in this list restricts the following ones:

Server level
Moodle site level
Course level
Activity level

This is a contentious issue, mainly because you might think that it should be set inside the Moodle. Unfortunately, this is not so, these are environment issues that need to be set in the server and PHP folders, Moodle cannot work outside itself.

==Physical access to Server==
These instructions assume you have full physical and administrative access to your server. If you are using a hosted server then you will probably need to look into other ways to increase your file upload size.

There are positives and negatives to both methods below. If you modify the pnp.ini file then the changes will effect all php applications on your server. Since PHP5 you can only have one php.ini file on your server. The php.ini method will work with all web servers though. The .htaccess method will only effect the folder and all subfolders that it is placed in, but you must have certain settings enabled in Apache.

===Modifying the php.ini file===
These instructions show you how to change the file upload size by editing your php.ini file.
====Ubuntu Linux Instructions====

These instructions assume that you have installed the standard Moodle package, PHP 5 and Apache 2 via apt-get and left it all as a default install. If you have compiled yourself I presume that you will know where your php.ini files are!

You need to edit the following three settings in your php.ini file located at: /etc/php5/apache2/

*Type "sudo nano /etc/php5/apache2/php.ini"
*Press Ctrl and W and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "max_execution_time"
*Change the value to 600
*Press Ctrl and O
*Press Ctrl and X
*Type sudo /etc/init.d/apache2 restart

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

====Windows XP and Server 2003 Instructions====

These instructions presume that you have downloaded the latest PHP 5.2.x Windows zip package and extracted it to C:\PHP. If you have installed PHP to another location then change all references to "C:\PHP" to the location you installed PHP too.

*Open C:\PHP
*Right Click the '''php.ini''' file in this folder and choose "Open with..."
*Choose "Wordpad" not "Notepad" to open the file with (Notepad does not properly use the UTF-8 Character set and it's carriage returns can cause problems)
**Better still download and install any text editor that can save the file in a UTF-8 format, [http://www.crimsoneditor.com Crimson Editor] is one such, and use that instead of either Wordpad or Notepad!
*Press Ctrl and F and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and F and type "max_execution_time"
*Change the value to 600
*Press Ctrl and S
*Exit Wordpad
*Restart your webserver
**'''For IIS'''
**Open your Start Menu on your server and select "Run"
**Type "iisreset /RESTART"
**'''For Apache 2'''
**The following command will work as long as you have installed Apache 2 as a service on your Windows Server
**Open your Start Menu on your server and select "Run"
**Type "httpd -k restart"

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

'''NOTE:''' These instructions should also cover the Xampp Windows installer. Just replace C:\PHP with C:\Moodle\server\php and to restart your Moode with a normal stop-start.

===Modifying the apache config file===
====Ubuntu Linux Instructions====
You may also need to edit the config.php file in the moodle directory:
*Type "gksudo nautilus" to get root permissions
*Navigate to /etc/moodle
*Open apache.conf
*Go to the "<IfModule mod_php5.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Go to the "<IfModule mod_php4.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Save file
*Type sudo /etc/init.d/apache2 restart

===Modifying the .htaccess file===
{{stub}}
The following instructions will only work on an Apache web server, and also the Apache server must have Overrides allowed. Additionally php must be running as an apache module, not as a cgi program.

Create a file called .htaccess in Moodle's main directory (where 'index.php' is located, not the 'moodledata' directory) that contains the following information:

php_value upload_max_filesize 20971520
php_value post_max_size 20971520
php_value max_execution_time 600

20971520 is the integer value for 20Mb. You can use the following site to [http://www.onlineconversion.com/computer_base2.htm convert MegaBytes to Bytes].

===Modifying the IIS 7.0/7.5 configuration (Windows Server 2008 SP2 & R2)===
First increase activity and request time outs (allows large files to succeed on slow connections)
FastCGI Settings > Edit (Right-click on PHP application
Set Process Model > Activity Timeout to '3600' (one hour)
Set Process Model > Request Timeout to '3600' (one hour)
Next set 'Maximum allowed content length'
Request Filtering > Edit Feature Settings:
Set 'Maximum allowed content length' to your desired file size (in bytes) e.g. '536870912' for 512MB (default is approximately 28.6MB)

==Hosted Server==
Things can be a little different with a hosted server for uploaded and downloaded file size. You are probably going to to be told to create or change a .htaccess file, or to modify a php.ini file.

:It might be a good idea to talk to with your service provider before you attempt anything. They probably have instructions on "how to" and may have their own limits for uploaded file size. Some hosts measure the file size in gigabytes and others in megabytes. If you are unhappy with their limits, then check your contract and consider changing your provider to one that has a limit and price that you like.

===.htaccess with hosted server===
The one purpose of an .htaccess file is to override the the current limitations of both the server and the php.ini file. Your hosted server should inform you where that file needs be placed in your Moodle, but generally in the root is sufficient. They may already have a standard file you can use, if so, use it - but perhaps not.

To the .htaccess file add the lines:
php_value upload_max_filesize 128M
php_value post_max_size 128M

This will limit uploads to 128MB, but you can make it any size you agree with your provider. The wording may vary slightly, according to the demands of the server.

===php.ini with hosted server===
Some servers will not allow you to change the moodle root .htaccess file and tell you to use a php.ini file for php directives. Here you can use the instruction located in the section above called [[File_upload_size#Modifying_the_php.ini_file|Modifying the php.ini file]].

Find the php.ini file in your moodle subfolder on your hosted server. You might want to copy the file as a backup just in case. Edit php.ini, find "upload_max_filesize" and post_max_size in the code. After the = change the number. Here the max filesize is 20 megabytes.

upload_max_filesize = 20M
post_max_size = 20M

:Tip: Still not changed? Some hosts using cpanel have a php config program under services/software. Use the "Single php.ini" option and make sure you note the location of the php.ini file to modify. This changes the .htaccess file in the same area and thus the server limit for all programs using php.

==See Also==
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F|Administration FAQ Doc page]]
*[[Site_policies#Maximum_uploaded_file_size|Site Policies Doc page]]
*[[Installing_Moodle/Creating_custom_php.ini_files|Creating custom php.ini files Doc Page]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=39625 Detailed instructions to increase the maximum allowed size for uploaded files] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97907 Instructions to increase maximum allowed size on hosted servers] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=124441 Help on changing the maximum upload size when installing Moodle via apt-get] forum discussion

[[Category:Administrator|File]][[Category:FAQ|File]]

MrCUTE

2009-12-08T14:43:09Z

Afhole: /* NLN (Noodle) */

MrCute is contributed code and a JISC funded project that extends the functionality of the IMS Repository system (Object module) originally developed by Alton College, UK. It adds the following main features:
* Searchable database index of all IMS Packages (backwards compatible with resources deployed through the current IMS Repository system)
* Editing of existing IMS Content Packages
* Create new packages from single files uploaded to Moodle, e.g. Images, Documents, Videos, Flash movies

[[Category: Contributed code]]

== Installation ==

Please refer to the readme file in the zip package:
[zip]:/blocks/mrcute/docs/README.txt

== NLN (Noodle) ==
To enable NLN/Noodle integration you must install Noodle, available from:
[http://www.nln.ac.uk/?p=Noodle Noodle]

MrCUTE

2009-12-08T14:42:46Z

Afhole:

MrCUTE

2009-11-13T15:44:47Z

Afhole: New page: MrCute is a JISC funded project that extends the functionality of the IMS Repository system (Object module) originally developed by Alton College, UK. It adds the following main features: ...

MrCute is a JISC funded project that extends the functionality of the IMS Repository system (Object module) originally developed by Alton College, UK. It adds the following main features:
Searchable database index of all IMS Packages (backwards compatible with resources deployed through the current IMS Repository system)
Editing of existing IMS Content Packages
Create new packages from single files uploaded to Moodle, e.g. Images, Documents, Videos, Flash movies

Installing MSSQL for PHP

2009-09-17T15:43:02Z

Afhole:

{{Moodle 1.7}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE mdl_HEAD SET ANSI_NULLS ON GO)
:* Quoted Identifiers Enabled = true (ALTER DATABASE mdl_HEAD SET QUOTED_IDENTIFIER ON GO)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Unix ==

'''Important Note 1:''' Due to [http://bugs.php.net/bug.php?id=39213 one bug in PHP] it's highly recommendable to use PHP > 5.1.6 with FreeTDS ([http://tracker.moodle.org/browse/MDL-11810 more info]).

'''Important Note 2:''' Due to one bug in how FreeTDS handles nulls and empty values for some text types it's highly recommendable to use a recent version of FreeTDS (0.64 + official patches) ([http://tracker.moodle.org/browse/MDL-11810#action_38005 more info]).

If you web server is on Linux or some other flavour of Unix, try FreeTDS, http://www.freetds.org (documentation at http://www.freetds.org/docs.html)

Note that the download link above is a '''source download''', so you will need to install and compile it properly.

Once downloaded and uncompressed you must '''"configure, make, make install"''' it. This will deploy some stuff in the "/usr/local" directory of your machine, mainly:
* /usr/local/etc: where the freetds conf files will reside.
* /usr/local/lib: where compiled libraries will reside.
* /usr/local/bin: where some executables will reside.

Then, you must configure FreeTDS to point to your MSSQL DB server. To do so, edit (or create) the /usr/local/etc/freetds.conf file and put in there exclusively these lines:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0 (or 8.0 if using FreeTDS 0.82 or later)
text size = 20971520

At this point, and previously to build the '''mssql extension alternative''', you can test conectivity with your MSSQL DB using the "/usr/local/bin/tsql" executable. Just do this:

tsql -S serverhost -U dbowner -P dbpassword

If everything is ok, you'll get this output:

locale is "es_ES.UTF-8"
locale charset is "UTF-8"
1>

just type, for example:

sp_help sysobjects

and you might get some output from DB. Finally type:

exit

and you'll be out from the "tsql" command line interpreter.

Now that you've successfully built, configured and tested FreeTDS it is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, you'll need configure your PHP server adding this new option to the usual ones:

--with-mssql=/usr/local/

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by FreeTDS.

Finally, configure your Moodle config.php with this DB related info and continue with a normal Moodle install:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'xxx.xxx.xxx.xxx'; // IP of the MSSQL server (also proper hostname is allowed)
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

== Using FreeTDS on Windows ==

'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows.

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| PHP 5.3.x || Both included || 0.82 + 20090904 patches || [http://tracker.moodle.org/secure/attachment/18402/php_dlib_ts-and-nts_php-5.3.x%29.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. Create a file called C:\freetds.conf with:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one) 
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable) 
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== Related links ==

[[Installing Oracle for PHP]]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Compiling FreeTDS under Windows

2009-09-17T13:40:43Z

Afhole: /* Requirements */

==Requirements==

* MSVC 6.0 (Microsoft Visual C++ 6.0) with Service Packs installed.
* FreeTDS (tested with [http://www.ibiblio.org/pub/Linux/ALPHA/freetds/stable/freetds-0.82.tar.gz version 0.82] + [http://freetds.sourceforge.net/post82.diff.gz post 0.82 patches] - updated 2009-03-02).
* PHP source files (tested with [http://www.php.net/get/php-5.2.6.tar.gz/from/a/mirror version 5.2.6])
* These packages (non-debug):
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/ :
*** binary-tools.zip
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/VC6/x86/ :
*** bindlib
*** libiconv
*** libxml
*** libxslt
*** zlib

==Build Steps==

* Create c:\dev
* Create c:\dev\php-build
* Uncompress all the packages listed in requirements and PHP into c:\dev\php-build (replacing all when uncompressing).
* Copy uncompressed [http://www.ibiblio.org/pub/Linux/ALPHA/freetds/stable/freetds-0.82.tar.gz freetds] folder to C:\dev\php-build (rename it to, simply, "freetds").
* Apply [http://freetds.sourceforge.net/post82.diff.gz post 0.82 patches] in the "freetds" dir.
* Open the C:\dev\php-build\freetds\win32\msvc6\FreeTDS.dsw Project Workspace (it's really important to get this Workspace and not any of the individual projects!).
* In the "Build" menu, set the "Active Configuration" to "dblib - Win32 Release" and then, in the same menu, "Rebuild All". This should end with one dblib.lib library into C:\dev\php-build\freetd\win32\msvc6\db_Release
* Copy dblib.lib to C:\dev\php-build\lib
* Start CMD
* Create one C:\dev\prepare4php.bat file with contents below and execute it:
::@set PATH=C:\dev\php-build\bin;%PATH%
::@set INCLUDE=C:\dev\php-build\include;%INCLUDE%
::@set LIB=C:\dev\php-build\lib;%LIB%
::@set BISON_SIMPLE=C:\dev\php-build\bin\bison.simple
* Continue in CMD and change dir to C:\dev\php-build\php-x-x-x
* Execute this:
** buildconf
** cscript /nologo configure.js --disable-all --disable-ipv6 --enable-zts (--disable-zts) --with-dblib=shared --enable-object-out-dir=c:\dev --with-extra-includes=c:\dev\php-build\freetds\include;c:\dev\php-build\freetds\win32
** nmake
* You should end with one C:\dev\Release_TS for the --enable-zts (or C:\dev\Release for the --disable-zts alternative) dir, with your compiled FreeTDS PHP module ready at the root level of that dir.

==Notes==
* By using --enable-zts or --disable-zts you'll end with different thread safe/no safe versions of the extension. Use them depending of your environment thread safety.
* If you one use PHP 5.2 version to build the lib, the extensions generated are expected to work against any PHP 5.2.x version (but not against other releases of PHP, like 5.1 or 5.3).
* MSVC 6.0 is required because it's the official tool used to build PHP binary distributions. It seems that, with PHP 5.3 they will start using MSVC 9 or so... corresponding extensions should use the same.
* Feel free to fix and improve this document. TIA!
* For any comment related to this, please use MDL-14725 in the Moodle Tracker.
* And MDL-11810 has a related discussion.

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Broken/Blocks

2009-04-30T10:38:33Z

Afhole: /* Lists and Icons */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T10:38:22Z

Afhole: /* Authorized Personnel Only */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T10:37:53Z

Afhole: /* Eye Candy */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => TRUE);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => TRUE,
'course-view-social' => FALSE);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => TRUE,
'course-view' => TRUE,
'course-view-social' => FALSE,
'mod' => TRUE,
'mod-quiz' => FALSE
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T10:37:45Z

Afhole: /* The Effects of Globalization */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return TRUE;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => TRUE);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => TRUE,
'course-view-social' => FALSE);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => TRUE,
'course-view' => TRUE,
'course-view-social' => FALSE,
'mod' => TRUE,
'mod-quiz' => FALSE
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T10:36:54Z

Afhole: /* We Are Legion */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return TRUE;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return TRUE;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => TRUE);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => TRUE,
'course-view-social' => FALSE);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => TRUE,
'course-view' => TRUE,
'course-view-social' => FALSE,
'mod' => TRUE,
'mod-quiz' => FALSE
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T10:36:26Z

Afhole: /* Configure That Out */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return TRUE;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return TRUE;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return TRUE;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => TRUE);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => TRUE,
'course-view-social' => FALSE);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => TRUE,
'course-view' => TRUE,
'course-view-social' => FALSE,
'mod' => TRUE,
'mod-quiz' => FALSE
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Broken/Blocks

2009-04-30T09:21:13Z

Afhole: /* config_save() */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a reference text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return TRUE;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(TRUE, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to /blocks/simplehtml/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return TRUE;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return TRUE;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return TRUE;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is /course/view.php (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => TRUE);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => TRUE,
'course-view-social' => FALSE);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => TRUE,
'course-view' => TRUE,
'course-view-social' => FALSE,
'mod' => TRUE,
'mod-quiz' => FALSE
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

NTLM authentication

2009-04-22T11:29:23Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>

function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T11:25:57Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>

function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}

</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:45:11Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:37:29Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/apache2/moodle.my-diploma.co.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:33:21Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

* Configure Apache / mod_auth_kerb
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:31:07Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

* Configure Apache / mod_auth_kerb
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:28:28Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create a '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

* Configure Apache / mod_auth_kerb
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:14:52Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create a '''user''' account

* Configure Apache / mod_auth_kerb
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:11:19Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
....
* Configure Apache / mod_auth_kerb
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:09:48Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:07:26Z

Afhole: /* Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
....

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:06:17Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

*Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T10:00:33Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
#'''Domain:''' EXAMPLE.AC.UK
#'''Domain controller:''' dc.example.ac.uk
#'''Moodle web server:''' moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:58:51Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
#'''Domain:''' EXAMPLE.AC.UK
#'''Domain controller:''' dc.example.ac.uk
#'''Moodle web server:''' moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</pre>

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:55:38Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
'''Domain:''' EXAMPLE.AC.UK
'''Domain controller:''' dc.example.ac.uk
'''Moodle web server:''' moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf

<code><nowiki>[libdefaults]
default_realm = EXAMPLE.AC.UK

[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}</nowiki></code>

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:52:50Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
'''Domain:''' EXAMPLE.AC.UK
'''Domain controller:''' dc.example.ac.uk
'''Moodle web server:''' moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf

<code><nowiki>
[libdefaults]
default_realm = EXAMPLE.AC.UK

[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}
</nowiki></code>

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:51:15Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
'''Domain:''' EXAMPLE.AC.UK
'''Domain controller:''' dc.example.ac.uk
'''Moodle web server:''' moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf
<code><nowiki>
[libdefaults]
default_realm = EXAMPLE.AC.UK

[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uke
}
</nowiki></code>

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:42:06Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

Environment details in this example:
Domain: EXAMPLE.AC.UK
Domain controller: dc.example.ac.uk
Moodle web server: moodle.example.ac.uk

Install kerberos on moodle.ac.uk and enter the following in /etc/krb5.conf
<code>
[libdefaults]
default_realm = EXAMPLE.AC.UK

[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uke
}
</code>

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:31:10Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)
:#...
:#...
*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:29:02Z

Afhole: /* Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
=====Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)=====

:*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:18:36Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
=====Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)=====

*Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:13:38Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
#Install and configure http://modauthkerb.sourceforge.net/
* Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above)

#Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:01:44Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
#Install and configure http://modauthkerb.sourceforge.net/
#Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2009-04-22T09:00:06Z

Afhole: /* Using the Kerberos Auth Module for Apache (mod_auth_kerb) */

{{Moodle 1.9}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

This is integrated into Moodle 1.9 onwards.

For earlier versions, it uses a modified version of LDAP Authentication.
The NTLM Authentication module is available in the Modules and Plugins database here:
http://moodle.org/mod/data/view.php?d=13&rid=314

Note: When a particular note is specific to earlier versions of the NTLM plugin, this is noted by: '''(pre-1.9 only)'''.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#'''(pre-1.9 only)''' You have "some" basic knowledge of php and are able to configure the index.php with the range of internal IP addresses.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': In Moodle 1.9 and onwards, NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Administration >> Users >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation on 1.9==

No installation needed. See the Administration >> Users >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Integrated Authentication
*On Apache - use one of the 3 methods outlined below

If you have used previous versions of NTLM in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==Installation on 1.6/1.7==
#Copy the folder AUTH/NTLM into the AUTH folder of your moodle installation.
#Configure the IP/Subnet Mask in the Config screen.
[https://docs.moodle.org/en/NTLM_authentication#Configuring IP/Subnet Mask see below for more help]
If the IP/Subnet Mask does not give enough complexity for your network, Modify the auth/ntlm/index.php file - for instructions on doing this, view the comments in the file.
#Turn Integrated Authentication ON and Anonymous Authentication OFF for the moodle\auth\ntlm\oncampuslogin.php file. [https://docs.moodle.org/en/NTLM_authentication#How_to_Turn_Integrated_Authentication_on see below for more detailed instructions]
#Visit the admin page of your moodle installation - you should see notification that the NTLM_AUTH module has been installed.
#go to the configuration > variables page, find the dbsessions setting (in 1.8 on admin page server \ sessions page), and set it to "YES" then save the page.
#go to the Authentication admin page and select auth_ntlmtitle as your authentication method Note: - this doesn't display full text as I haven't created a language file for this module - you will also see auth_ntlmdescription instead of a proper description - you don't need to worry about this, as you will be the only one who ever sees this.
#Configure this page with your normal LDAP settings. NOTE: the Alternate Login URL at the bottom of this page (or on the main authentication page in 1.8 - and needs to be set manually to the oncampus url)has been set to the NTLM page. - if you wish uninstall this auth module, you must reset this variable on the new authentication type page. eg - if you wish to revert back to manual authentication, then change to manual, and then make sure you delete the alternate login url at the bottom of the page.
#(OPTIONAL) modify the offcampuslogin page to give errors when students try to prefix their usercode with your domain.
around line 216 find this code, uncomment all the lines and replace the letters 'DOM' with your domain:

if (empty($errormsg)) {
if (strstr(strtolower($frm->username), "DOM\\") <> false) { //NAD - DOM messages.
$errormsg = get_string("invalidlogin") . " DOM\\ is not required!";
} else if (strpos($frm->username, "@") <> false) {
$errormsg = get_string("invalidlogin") . " enter your username - not your e-mail address.";
} else {
$errormsg = get_string("invalidlogin");
}
}

==Installation on 1.5==

See the README in the auth/ntml package.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php (1.9 or above) or oncampuslogin.php (1.8 or below) MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.
===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php (1.9 or above) or auth/ntlm/oncampuslogin.php (1.8 or below) file,
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"
===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba (Linux)====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain. You'll need to type this account's password for the command to succeed.

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are goint to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Restart the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core, keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138 
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)

====Using the NTLM Auth Module for Apache====
#get the Module from: http://modntlm.sourceforge.net/
#use something like this in your httpd.conf: http://moodle.org/mod/forum/discuss.php?d=45887#211074

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:: '''For 1.9 or above''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:: '''For 1.8 or below''':
:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ntlm' and add the following directives:
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache (mod_auth_kerb)====
#Install and configure http://modauthkerb.sourceforge.net/
#Replace the ntlmsso_magic function in /auth/ldap/auth.php (1.9 and later only?) with the following code:

<code php>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

$username = $_SERVER['REMOTE_USER'];

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ( $pos = strpos($username, "@") )
{
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

// $username = substr(strrchr($username, '\\'), 1); //strip domain info
$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</code>

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.
* '''(pre-1.9 only)''' Once you have configured your IP/Subnet masks, you can use the check_ip.php page to test if you have set these ranges up correctly.
* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==
# '''(pre-1.9 only)''' When using IIS, dbsessions is required to be set to "YES" because when Integrated authentication is turned on for the oncampuslogin.php page, and dbsessions is set to "NO" then the server impersonates the user to write the session in the moodledata\sessions folder. The recommended fix is to set dbsessions to "YES" so that sessions are stored in the db. The non-recommended alternative method is to allow domain users write access to the sessions directory.
# '''(pre-1.9 only)''' If you forget to change the internal IP addresses in index.php to your own, you can just use the offcampuslogin url to login using your admin account. eg: http://yoursite.com/moodle/auth/ntlm/offcampuslogin.php
#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.

==Specific File information (pre-1.9 only)==
(mainly for developers)
#auth\ntlm\index.php This is the page used for the Alternate Login URL setting on the config page for the NTLM plugin. The index.php file handles which login page to use based on the IP address of the user. if inside your network, they should be directed to the oncampuslogin.php screen. if outside your network, they should be directed to the offcampuslogin.php screen. you will need to modify the if statements in this file to match the IP ranges inside your network.
#auth\ntlm\index_form.html this is a copy of the file login\index_form.php. The only change in this file from the standard one is that the form action="index.php" is changed to form action="offcampuslogin.php" this is because anyone who is displayed the form will be an offcampus user.
#auth\ntlm\offcampuslogin.php this is a copy of the file moodle\login\index.php with a couple of minor modifications. the modifications to this file involve the setting of a variable ($onoroffcampus = "offcampus";) this is used by the auth plugin to define which page is being used for authentication. the other modification is for displaying extra error messages to the user. - with all the authentication methods we have students are constantly confused about how to enter their credentials if you use NTLM authentication elsewhere at your site you will be aware of the users having to enter the domain\username when authenticating. - this code block sits around line 215 in the file.
#auth\ntlm\oncampuslogin.php this is a copy of the file login\index.php This file has been modified to get the details of the authenticated user via NTLM.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]