How to manage user credentials

Overview

Symfony offers simple mechanisms to identify a user, manage his credentials and restrict access to certain parts of your applications to authenticated users with certain credentials only.

User identification

The authenticated status of the user is set by the ->setAuthenticated() method of a sfUser/myUser object. For instance, if you need to implement a simple version of user identification in a module called myAccount with two actions login and logout, you can write:

class myAccountActions extends sfActions
{
  public function executeLogin()
  {
    if ($this->getRequestParameter('login') == 'admin')
    {
      $this->getUser()->setAuthenticated(true);
    }
  }
 
  public function executeLogout()
  {
    $this->getUser()->setAuthenticated(false);
  }
}

User credentials

For authenticated users, symfony provides an array of credentials in the sfUser class that can be set via simple access methods has, add, remove and clear. Each credential can have any value.

$user = $this->getUser();
// add a credential
$user->addCredential($credential);
// add several credentials at once
$user->addCredentials($credential1, $credential2);
// check if the user has a credential
$user->hasCredential($credential)                  =>   true
// remove a credential
$user->removeCredential($credential);
$user->hasCredential($credential)                  =>   false
// remove all credentials
$user->clearCredentials();
$user->hasCredential($credential1)                 =>   false

Here is an example of credential definition:

class myAccountActions extends sfActions
{
  public function executeLogin()
  {
    if ($this->getRequestParameter('login') == 'superuser')
    {
      $user = $this->getUser();
      $user->setAuthenticated(true);
      $user->addCredential('superuser');
    }
    if ($this->getRequestParameter('login') == 'admin')
    {
      $user = $this->getUser();
      $user->setAuthenticated(true);
      $user->addCredentials('admin', 'superuser');
    }
  }
 
  public function executeRemoveSomeCredential()
  {
    $user = $this->getUser();
    if ($user->hasCredential('admin', 'superuser'))
    {
      $user->removeCredential('superuser');
    }
    if ($user->hasCredential('admin'))
    {
      $user->removeCredential('admin');
    }
  }
 
  public function executeLogout()
  {
    $user = $this->getUser();
    $user->clearCredentials();
    $user->setAuthenticated(false);
  }
}

Access restriction

Now that the user can be authenticated and given credentials, it is time to restrict access to some of your actions to grant access only to a subset of users.

This will be done with the security.yml module configuration file. This file can be found in the myproject/apps/myapp/modules/mymodule/config/ (if it doesn't exist for your module, create it).

For example, to restrict the read action of the myAccount module to users with 'customer' credential, and the update action to the users with 'admin' or 'superuser' credentials, the security.yml file of the myproject/apps/myapp/modules/myAccount/config/ directory will have to look like:

read:
  is_secure:   on
  credentials: customer

update:
  is_secure:   on
  credentials: [admin, superuser]

all:
  is_secure:  off

What happens when a user tries to access a restricted action depends on his credentials:

• If the user is identified and has the proper credentials, the action will be executed
• If the user is not identified, he/she will be redirected to the default login action (default/login). You can configure this action in the myproject/apps/myapp/config/settings.yml file.
• If the user is identified but doesn't have the proper credentials, he/she will be redirected to the default secure action (default/secure). You can configure this action in the myproject/myapp/config/settings.yml file.

The power of credentials with AND and OR

The YAML syntax used in the security.yml allows you to restrict access to users having a combination of credentials, using either AND-type or OR-type associations:

credentials: [ admin, superuser ]          ## admin AND superuser
credentials: [[ admin, superuser ]]        ## admin OR superuser
credentials: [[ admin, superuser ], owner] ## (admin OR superuser) AND owner

Session expiration

The session expiration is described in detail in the user session chapter.