authentication.rst 5.2 KB

  1. Authentication
  2. ==============
  3. Elgg provides everything needed to authenticate users via username/email and password
  4. out of the box, including:
  5. * remember-me cookies for persistent login
  6. * password reset logic
  7. * secure storage of passwords
  8. * logout
  9. * UIs for accomplishing all of the above
  10. All that's left for you to do as a developer is to use
  11. the built-in authentication functions to secure your pages and actions.
  12. Working with the logged in user
  13. -------------------------------
  14. Check whether the current user is logged in with ``elgg_is_logged_in()``:
  15. .. code:: php
  16. if (elgg_is_logged_in()) {
  17. // do something just for logged-in users
  18. }
  19. Check if the current user is an admin with ``elgg_is_admin_logged_in()``:
  20. .. code:: php
  21. if (elgg_is_admin_logged_in()) {
  22. // do something just for admins
  23. }
  24. Get the currently logged in user with ``elgg_get_logged_in_user_entity()``:
  25. .. code:: php
  26. $user = elgg_get_logged_in_user_entity();
  27. The returned object is an ``ElggUser`` so you can use all the methods and properties
  28. of that class to access information about the user. If the user is not logged in,
  29. this will return ``null``, so be sure to check for that first.
  30. Gatekeepers
  31. -----------
  32. Gatekeeper functions allow you to manage how code gets executed by applying access control rules.
  33. Forward a user to the front page if they are not logged in with ``elgg_gatekeeper()``:
  34. .. code:: php
  35. elgg_gatekeeper();
  36. echo "Information for logged-in users only";
  37. .. note::
  38. In Elgg 1.8 and below this function was called ``gatekeeper()``
  39. Forward a user to the front page unless they are an admin with ``elgg_admin_gatekeeper()``:
  40. .. code:: php
  41. elgg_admin_gatekeeper();
  42. echo "Information for admins only";
  43. .. note::
  44. In Elgg 1.8 and below this function was called ``admin_gatekeeper()``
  45. Prevent CSRF attacks with ``action_gatekeeper()``.
  46. .. code:: php
  47. action_gatekeeper();
  48. // Mutate some state in the database on behalf of the logged in user...
  49. This function should be used in :doc:`actions` prior to Elgg 1.8.
  50. .. note::
  51. As of Elgg version 1.8 this function is called for all registered actions.
  52. There is no longer a need to call this function in your own actions.
  53. If you wish to protect other pages with action tokens then you can call this function.
  54. Pluggable Authentication Modules
  55. --------------------------------
  56. Elgg has support for pluggable authentication modules (PAM), which enables you to write your own authentication handlers. Whenever a request needs to get authenticated the system will call ``elgg_authenticate()`` which probes the registered PAM handlers until one returns success.
  57. The preferred approach is to create a separate Elgg plugin which will have one simple task: to process an authentication request. This involves setting up an authentication handler in the plugin's :doc:`start.php <plugins>` file, and to register it with the PAM module so it will get processed whenever the system needs to authenticate a request.
  58. The authentication handler is a function and takes a single parameter. Registering the handler is being done by ``register_pam_handler()`` which takes the name of the authentication handler, the importance and the policy as parameters. It is advised to register the handler in the plugin's init function, for example:
  59. .. code:: php
  60. function your_plugin_init() {
  61. // Register the authentication handler
  62. register_pam_handler('your_plugin_auth_handler');
  63. }
  64. function your_plugin_auth_handler($credentials) {
  65. // do things ...
  66. }
  67. // Add the plugin's init function to the system's init event
  68. elgg_register_elgg_event_handler('init', 'system', 'your_plugin_init');
  69. Importance
  70. ----------
  71. By default an authentication module is registered with an importance of **sufficient**.
  72. In a list of authentication modules; if any one marked *sufficient* returns ``true``, ``pam_authenticate()`` will also return ``true``. The exception to this is when an authentication module is registered with an importance of **required**. All required modules must return ``true`` for ``pam_authenticate()`` to return ``true``, regardless of whether all sufficient modules return ``true``.
  73. Passed credentials
  74. ------------------
  75. The format of the credentials passed to the handler can vary, depending on the originating request. For example, a regular login via the login form will create a named array, with the keys ``username`` and ``password``. If a request was made for example via XML-RPC then the credentials will be set in the HTTP header, so in this case nothing will get passed to the authentication handler and the handler will need to perform steps on its own to authenticate the request.
  76. Return value
  77. ------------
  78. The authentication handle should return a ``boolean``, indicating if the request could be authenticated or not. One caveat is that in case of a regular user login where credentials are available as username and password the user will get logged in. In case of the XML-RPC example the authentication handler will need to perform this step itself since the rest of the system will not have any idea of either possible formats of credentials passed nor its contents. Logging in a user is quite simple and is being done by ``login()``, which expects an ``ElggUser`` object.