root/plugins/sfGuardPlugin/README

= sfGuard plugin =

!!! ALPHA RELEASE !!!

The `sfGuardPlugin` is a symfony plugin that provides authentication and authorization features above the standard security feature of symfony.

It gives you the model (user, group and permission objects) and the modules (backend and frontend) to secure your symfony application in a minute in
a configurable plugin.

== Installation ==

  * Install the plugin
  
  {{{
    symfony plugin-install http://plugins.symfony-project.com/sfGuardPlugin
  }}}
  
  * Rebuild your model
  
  {{{
    symfony propel-build-all
  }}}
  
  * Load default fixtures (optional - it creates a superadmin user)
  
  {{{
    symfony propel-load-data
  }}}
  
  * Enable one or more modules in your `settings.yml` (optional)
    * For your backend application:  sfGuardUser, sfGuardGroup, sfGuardPermission
    * For your frontend application: sfGuardAuth

  {{{
    all:
      .settings:
        enabled_modules:      [default, sfGuardGroup, sfGuardUser, sfGuardPermission]
  }}}

  * Clear you cache
  
  {{{
    symfony cc
  }}}

=== Secure your application ===

To secure a symfony application:

  * Enable the module `sfGuardAuth` in `settings.yml`

  {{{
    all:
      .settings:
        enabled_modules: [..., sfGuardAuth]
  }}}

  * Change the default login and secure modules in `settings.yml`

  {{{
    login_module:           sfGuardAuth
    login_action:           signin

    secure_module:          sfGuardAuth
    secure_action:          secure
  }}}

  * Change the user class in `factories.yml`

  {{{
    all:
      user:
        class: sfGuardSecurityUser
  }}}

  * Add the following routing rules to `routing.yml`

  {{{
    sf_guard_signin:
      url:   /login
      param: { module: sfGuardAuth, action: signin }

    sf_guard_signout:
      url:   /logout
      param: { module: sfGuardAuth, action: signout }

    sf_guard_password:
      url:   /request_password
      param: { module: sfGuardAuth, action: password }
  }}}

  You can customize the `url` parameter of each route.
  N.B.: You must have a `@homepage` routing rule (used when a user sign out)

  * Secure some modules or your entire application in `security.yml`

  {{{
    default:
      is_secure: on
  }}}

  * You're done. Now, if you try to access a secure page, you will be redirected to the login page.
    If you have loaded the default fixture file, try to login with `admin` as username and `admin` as password.

== Manage your users, permissions and groups ==

To be able to manage your users, permissions and groups, `sfGuardPlugin` comes with 3 modules that can be integrated in your backend application.
These modules are auto-generated thanks to the symfony admin generator.

  * Enable the modules in `settings.yml`

  {{{
    all:
      .settings:
        enabled_modules: [..., sfGuardGroup, sfGuardPermission, sfGuardUser]
  }}}

  * Access the modules with the default route:
 
  {{{
    http://www.example.com/backend.php/sfGuardUser
  }}}

== Customize sfGuardAuth module templates ==

By default, `sfGuardAuth` module comes with 2 very simple templates:

  * `signinSuccess.php`
  * `secureSuccess.php`

If you want to customize one of these templates:

  * Create a `sfGuardAuth` module in your application
 
  * Create a template with the name of the template you want to customize in your `templates` directory

  * Symfony now renders your template instead of the default one

== Customize `sfGuardAuth` module actions ==

If you want to customize or add methods to the sfGuardAuth:

  * Create a `sfGuardAuth` module in your application
  
  * Create an `actions.class.php` file in your `actions` directory that inherit from `BasesfGuardAuthActions`

  {{{
    <?php

    class sfGuardAuthActions extends BasesfGuardAuthActions
    {
      public function executeNewAction()
      {
        return $this->renderText('This is a new sfGuardAuth action.');
      }
    }
  }}}

== `sfGuardSecurityUser` class ==

This class inherits from the `sfBasicSecurityUser` class from symfony and is used for the `user` object in your symfony application
(because you configured it in `factories.yml` before).

So, to access it, you can use the standard `$this->getUser()` in your actions or `$sf_user` in your templates.

`sfGuardSecurityUser` adds some methods:

  * `signIn()` and `signOut()` methods
  * `getGuardUser()` that returns the `sfGuardUser` object
  * a bunch of proxy methods to access directly the `sfGuardUser` object

For example, to get the current username:

  {{{
    $this->getUser()->getGuardUser()->getUsername()

    // or via the proxy method
    $this->getUser()->getUsername()
  }}}

== Super administrator flag ==

`sfGuardPlugin` has a notion of super administrator. A user that is a super administrator bypasses all credential checks.

The super administrator flag cannot be set on the web, you must set the flag directly in the database or use the pake task:

  {{{
    symfony promote-super-admin admin
  }}}

== Validators ==

`sfGuardPlugin` comes with a validator that you can use in your modules: `sfGuardUserValidator`.

This validator is used by the `sfGuardAuth` module to validate a user and password and automatically signin the user.

== Customize the `sfAuthUser` model ==

The `sfAuthUser` model is quite simple. There is no `email` or `first_name` or `birthday` columns.
As you cannot add methods to the class, the `sfAuthPlugin` gives you the possibility to define a user profile class.

By default, `sfAuthUser` looks for a `sfGuardUserProfile` class.

Here is a simple example of a `sfGuardProfile` class that you can add to `schema.yml`:

  {{{
    sf_guard_user_profile:
      _attributes: { phpName: sfGuardUserProfile }
      id:
      user_id:     { type: integer, index: unique }
      first_name:  varchar(20)
      last_name:   varchar(20)
      birthday:    date
  }}}

WARNING: You cannot define the foreign key because the `sf_guard_user` table is not in the same schema file (this is a Propel limitation).

This is why we added a unique index to the `user_id` column.

You can now access the user profile via the user object:

  {{{
    $this->getUser()->getGuardUser()->getProfile()->getFirstName()

    // or via the proxy method
    $this->getUser()->getProfile()->getFirstName()
  }}}

The `getProfile()` method gets the associated user profile object or creates a new one if none already exists.

When you delete a user, the associated profile is also deleted.

You can change the name of the user profile class and the foreign key name in `app.yml`:

  {{{
    all:
      sf_guard_plugin:
        profile_class:      sfGuardUserProfile
        profile_field_name: user_id            # we have to define this (see warning above)
  }}}

== Check the user password with an external method ==

If you don't want to store the password in the database because you already have a LDAP server, a .htaccess file or if you store
your passwords in another table, you can provide your own `checkPassword` callable (static method or function) in `app.yml`:

  {{{
    all:
      sf_guard_plugin:
        check_password_callable: [MyLDAPClass, checkPassword]
  }}}

When symfony will call the `$this->getUser()->checkPassword()` method, it will call your method or function. Your function must takes 2 parameters,
the first one is the username and the second one is the password. It must returns true or false. Here is a template for such a function:

  {{{
    function checkLDAPPassword($username, $password)
    {
      $user = LDAP::getUser($username);
      if ($user->checkPassword($password))
      {
        return true;
      }
      else
      {
        return false;
      }
    }
  }}}

== Change the algorithm used to store passwords ==

By default, passwords are stored as a `sha1()` hash. But you can change this with any callable in `app.yml`:

  {{{
    all:
      sf_guard_plugin:
        algorithm_callable: [MyCryptoClass, MyCryptoMethod]
  }}}

or

  {{{
    all:
      sf_guard_plugin:
        algorithm_callable: md5
  }}}

As the algorithm is stored for each user, you can change your mind later without the need to regenerate all passwords
for the current users.

== TODO ==

  * finish the `promote_super_user` task
  * finish the `getPassword` method
  * add support for HTTP Basic authentication
  * add a "remember me" feature?