sfGuard plugin
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)
Clear your cache
symfony cc
Optionally enable the "Remember Me" filter in factories.yml
all:
security_filter:
class: sfGuardBasicSecurityFilter
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 parent class in myUser.class.php
class myUser extends sfGuardSecurityUser
{
}
Optionally 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)
These routes are automatically registered by the plugin if the module sfGuardAuth is enabled unless you defined sfGuardPlugin_routes_register to false
in the app.yml configuration file.
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.phpsecureSuccess.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() methodsgetGuardUser() 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: [checkPassword](MyLDAPClass,)
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: [MyCryptoMethod](MyCryptoClass,)
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
