This page first gives an overview of the authentication process and then explains how authentication modules can be used to hook into that process and take over from the native authentication in Moodle.

== Overview of Moodle authentication process ==
The authentication use case in Moodle starts when a user clicks on the Login link in the UI. Then the following happens (skipping some minor details and rarer scenarios):

# If using the default login page, the page /login/index.php is displayed, asking for the user's credentials. OR, if a system administrator has set the Alternate Login URL on the "Manage authentication" page, that URL will be displayed.
# User enters their credentials and submits the form.
# The handler code in /login/index.php runs:
## It gets a list of enabled authentication plugins.
## It runs loginpage_hook() for each plugin, in case any of them needs to intercept the login request.
## It checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## It calls authenticate_user_login() in /lib/moodlelib.php, which returns a $user object. (Details of this code follow this main outline.)
## It determines whether authentication was successful (by checking whether $user is a valid object) and, if not, sends them back to the login page with an error message. Otherwise, it figures out where to send the user based on their original page request, whether their password is expired, etc., and redirects them there.

That's the main outline, but a lot of interesting stuff happens in authenticate_user_login():

# It gets a list of enabled authentication plugins.
# It looks up the username in the mdl_user table to see if they are allowed to log in, and which authentication plugin handles their login requests. (This will be the plugin that handled their first-ever login request.)
# It creates a user object, which will contain the data from mdl_user if the username is known; if not, it will be an empty object.
# It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
## Calls the user_login() function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
## If the plugin authenticates against an external system (not Moodle's user database), its update_user_record() function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's sync_roles() function (I am not clear what this is exactly supposed to do).
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's user_authenticated_hook() function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

== Creating and enabling an authentication plugin ==
To create and register an authentication plugin, do the following:

# Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
# Under your Moodle installation root, create the directory /auth/sentry. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file /auth/sentry/auth.php. Within the file, create a class auth_plugin_sentry that extends auth_plugin_base from /lib/authlib.php. (You will need to require_once the authlib file.)
# Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
# Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as <nowiki>[[auth_sentrytitle]]</nowiki>. You can enable it and move it up and down in the order. '''At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.'''
# If you don't like seeing <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory /auth/sentry/lang, and under it, a directory for each language that your installation needs to support. (Example: /auth/sentry/lang/en_us_utf8.) Within each of these language directories, create a file called auth_sentry.php. That file should set the desired value for $string['auth_sentrytitle'] for that language. You can also set the plugin description by setting $string['auth_sentrydescription'], and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en_us_utf8''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language / locale codes used in your moodle installation. For example, the lang folder in my system contained two folders named '''en''' and '''en_utf8'''. I emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. For more information on how Moodle handles such language files, see [[Development:Places_to_search_for_lang_strings]].
# If you want to configure your plugin through the Moodle UI, implement config_form() and process_config() in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_pluginstable in the database.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion

[[Category:Authentication]]

[[fr:Méthodes_d'authentification]]

Development talk:Roles

2010-10-23T19:26:08Z

Wmasterj: /* Let's start a new guideline for the wiki */

Chris, I put back the forum moderator example. I think it was intentional. We want to get people thinking outside the box of what previous versions were capable of.

-----

The list of capabilities for some activities should include viewing as a separate capability since it is a distinct action from editing or taking part, for example

choice_canviewresults

== legacy support for isstudent() and isteacher() ==

We could provide legacy support for modules (and core) to continue using isstudent() and isteacher() calls, by replacing these with stubs that simply wrap the new access control API and feed in the proper parameters. This might help reduce the initial effort (i.e., you don't HAVE to update every. single. module. at first, just the ones most affected by this API change. then, as time allows, and as modules are being updated anyway, migrate them to the new API)

almost forgot - totally looking forward to this feature. any ETA?

== What are the legacy capabilities for? ==

I've been reading the Roles documentation, and my a lot of work going on in here! Keep it up! I might be understanding something incorrectly as I can't figure out what the legacy capabilities are for? I thought that Roles are sets of capabilities. There might/should be Roles for all of the "legacy roles", which would then have the default set of capabilities matching the capabilities in 1.6. What are the "legacy capabilities" then? --[[User:Samuli Karevaara|Samuli Karevaara]] 07:27, 1 September 2006 (CDT)
:No answer yet... This was also asked in the [http://moodle.org/mod/forum/discuss.php?d=61269 forums]. --[[User:Samuli Karevaara|Samuli Karevaara]] 04:43, 18 January 2007 (CST)

== Page too long? ==

I think this page is a bit too long and could profit from some refactoring, for example reducing some redundancies with other pages like [[Development:Roles and modules]] or integrating [[Development:Local customisation]]. --[[User:Frank Ralf|Frank Ralf]] 17:14, 27 March 2009 (UTC)

== Let's start a new guideline for the wiki ==

I am a new user and developer for Moodle at the University of Washington and time and time again I get frustrated about the use of first person everywhere:

"I added these questions here because..."

Who cares about you? I suggest a new guideline that encourages everyone to write more like:

"Here follows a questions section, the reason we have it is..."

I get pretty turned of myself to edit any documentation in this Wiki because there are so many "I"'s everywhere that it seems like one or two people are editing everything and if I do any thing to it that person would get upset. This is wrong an is an inhibitor to the fact that you probably want loads of people adding to and editing the wiki. Since I am new, please forward this to some wiki admin who can take this into consideration and add to a guideline somewhere (i don't know where they are).

Thanks --[[User:Jeroen van den Eijkhof|Jeroen van den Eijkhof]] 04:10, 23 October 2010 (UTC)

: I have no idea how the above comment relates to the [[Development:Roles]] page. If you want to hold a meta-discussion about Moodle documentation, http://moodle.org/mod/forum/view.php?id=5838 might be a better place.

: It think it is reasonable to distinguish content on this wiki that is uncontroversial statements of fact (This is how X works: ...) from parts that are one particular opinion on a topic, but where other opinions are possible (I find that a good way to structure my files is ... --Tim]]. Of course this wiki is not the place for personal expressions of idiosyncratic opinions, but when you are writing something in the hope that it will be useful to a lot of people most of the time, but which in not the only right way, I think it is reasonable to flag this is some way, and using I, with a signature, so people can judge the source of the advice, seems like a reasonable approach to me.--[[User:Tim Hunt|Tim Hunt]] 07:22, 23 October 2010 (UTC)

:: Yes, that is reasonably. But clear and structured communication is so important when it comes to the growth of an open source community. And if you do voice a personal opinion that could be put in the discussion page or if you do put that in the documentation and no one changes it then that should be a sign of it being. --[[User:Jeroen van den Eijkhof|Jeroen van den Eijkhof]] 19:26, 23 October 2010 (UTC)

2010-10-23T05:50:58Z

Wmasterj: /* Core components */

[[image:moodle-development-logo.jpg|right|400px]]

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.

* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].
<br />
<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches.<br /><br />

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Developer|Sort key]]</nowiki></code> to provide a sort key other than the default page name.</p>

==How Moodle development works==

The [[Development:Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Development:Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Development:Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Development:Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Development:Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.
*[[Development:Development hints and tips]] a (developing) list of general wisdom to help with your Moodle projects.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Development:Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[Development:PHPXref|PHPXref]].

===Getting started===

* (2-3 getting started links here)

===Core components ===

*[[Development:Database schema introduction|The database schema]]
*[[Development:What happens when you require config.php|What happens when you require config.php]]
*[[Development:lib/moodlelib.php|lib/moodlelib.php]]
*[[Development:lib/weblib.php|lib/weblib.php]] for outputting stuff
*[[Development:JavaScript_functions|JavaScript function available on the client side]]
*[[Development:XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Development:Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[Development:lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Development:Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Development:Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Development:Groups|Groups system]]
*[[Development:Grades|Gradebook]]
*[[Development:Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[Development:lib/graphlib|lib/graphlib]]
*[[Development:Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Development:Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Development:Modules|Activity modules]], see also [[Development:NEWMODULE Documentation]] (work in progress)
*[[Development:Admin reports|Admin reports]]
*[[Development:Assignment types|Assignment types]]
*[[Development:Authentication plugins|Authentication plugins]]
*[[Development:Blocks|Blocks]]
*Content editors (2.0 onwards)
*[[Course formats]]
*[[Development:Course Report Plugins|Course reports]]
*Course importers (2.0 onwards)
*[[Development:Database fields|Database fields]]
*[[Development:Database presets|Database presets]]
*[[Development:Enrolment plugins|Enrolment plugins]]
*[[Development:Filters|Filters]]
*[[Development:Gradebook_Report_Tutorial|Gradebook report]]
*[[Development:Gradebook export|Gradebook export]]
*[[Development:Gradebook import|Gradebook import]]
*Message senders (2.0 onwards)
*Mnet services
*Plagiarism detection plugins (2.0 onwards)
*[[Development:Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Development:Question_type_plugin_how_to|Question types]]
*[[Development:Question import/export formats|Question import/export formats]]
*[[Development:How to write a quiz report plugin|Quiz reports]]
*[[Development:Repository plugins|Repository plugins]] (2.0 onwards)
*[[Development:Resource types|Resource types]]
*[[Development:Search engine adapters|Search engine adapters]]
*Themes which are different in [[Development:Themes_2.0|Moodle 2.0]], and [[Theme_basics|earlier versions]].
*User profile fields
*Web services (2.0 onwards)
*Workshop allocators (2.0 onwards)
*Workshop forms (2.0 onwards)
*Workshop evaluators (2.0 onwards)

General information that applies to all types of plugins
*[[Development:Places to search for lang strings|Where to put language strings for your plugin]]
*[[Development:Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Development:Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Development:Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[Development:How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Development:Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Development:Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Development:Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Development:Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Development:Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled nightly from the comment attached to each class and function in the code.
*[[Development:Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Development:Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Development:Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[Development:vim|Setting up Vim for Moodle development]]
* [http://www.aptana.com/ Aptana Studio 2]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Development:Firebug]].
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[Development:ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Development:Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer]]
[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]
[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[pt:Desenvolvimento:Documentação para programadores]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]
[[fi:Ohjelmoijan opas]]

2010-10-23T04:10:16Z

Wmasterj: /* Let's start a new guideline for the wiki */ new section