Skip to content
Browse files

docs(auth): Add basic APIs to the authentication docs

  • Loading branch information...
ewinslow authored and mrclay committed May 23, 2015
1 parent d9721ab commit 83d5f214b73efbf743af9bbbd6f17b772a977a5e
Showing with 89 additions and 36 deletions.
  1. +89 −0 docs/guides/authentication.rst
  2. +0 −35 docs/guides/gatekeeper.rst
  3. +0 −1 docs/guides/index.rst
@@ -1,6 +1,95 @@

Elgg provides everything needed to authenticate users via username/email and password
out of the box, including:

* remember-me cookies for persistent login
* password reset logic
* secure storage of passwords
* logout
* UIs for accomplishing all of the above

All that's left for you to do as a developer is to use
the built-in authentication functions to secure your pages and actions.

Working with the logged in user

Check whether the current user is logged in with ``elgg_is_logged_in()``:

.. code:: php
if (elgg_is_logged_in()) {
// do something just for logged-in users
Check if the current user is an admin with ``elgg_is_admin_logged_in()``:

.. code:: php
if (elgg_is_admin_logged_in()) {
// do something just for admins
Get the currently logged in user with ``elgg_get_logged_in_user_entity()``:

.. code:: php
$user = elgg_get_logged_in_user_entity();
The returned object is an ``ElggUser`` so you can use all the methods and properties
of that class to access information about the user. If the user is not logged in,
this will return ``null``, so be sure to check for that first.


Gatekeeper functions allow you to manage how code gets executed by applying access control rules.

Forward a user to the front page if they are not logged in with ``elgg_gatekeeper()``:

.. code:: php
echo "Information for logged-in users only";
.. note::

In Elgg 1.8 and below this function was called ``gatekeeper()``

Forward a user to the front page unless they are an admin with ``elgg_admin_gatekeeper()``:

.. code:: php
echo "Information for admins only";
.. note::

In Elgg 1.8 and below this function was called ``admin_gatekeeper()``

Prevent CSRF attacks with ``action_gatekeeper()``.

.. code:: php
// Mutate some state in the database on behalf of the logged in user...
This function should be used in :doc:`actions` prior to Elgg 1.8.

.. note::

As of Elgg version 1.8 this function is called for all registered actions.
There is no longer a need to call this function in your own actions.
If you wish to protect other pages with action tokens then you can call this function.

Pluggable Authentication Modules

This file was deleted.

@@ -15,7 +15,6 @@ Customize Elgg's behavior with plugins.

0 comments on commit 83d5f21

Please sign in to comment.
You can’t perform that action at this time.