Wallogit.com
2017 © Pedro Peláez
Identity management plugin for symfony
The sfDoctrineGuardPlugin is a symfony plugin that provides authentication and
authorization features above and beyond the standard security features of symfony., (*1)
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., (*2)
Beginning with version 5.0.0 (the 1.4 stable branch), sfDoctrineGuardPlugin also
provides the option of applying for an account through the site (this is disabled
by default), and the ability to reset your password if you have forgotten it.
For security, password reset requires that you know the email address associated with the
account and be able to receive mail there. However applying for an account does not yet require receiving
an email message in 5.0.0., (*3)
The 5.x series can require significant migration effort when moving from earlier releases. See the Upgrade section for more information., (*4)
Install the plugin (via composer), (*5)
composer require lexpress/sf-doctrine-guard-plugin
Activate the plugin in the config/ProjectConfiguration.class.php, (*6)
php
class ProjectConfiguration extends sfProjectConfiguration
{
public function setup()
{
$this->enablePlugins(array(
'sfDoctrinePlugin',
'sfDoctrineGuardPlugin',
'...'
));
}
}, (*7)
Rebuild your model, (*8)
symfony doctrine:build-model symfony doctrine:build-sql
Update you database tables by starting from scratch (it will delete all the existing tables, then re-create them):, (*9)
symfony doctrine:insert-sql
or do everything with one command, (*10)
symfony doctrine-build-all-reload frontend
or you can just create the new tables by using the generated SQL
statements in data/sql/plugins.sfGuardAuth.lib.model.schema.sql, (*11)
Load default fixtures (optional - it creates a superadmin user), (*12)
mkdir data/fixtures/ cp plugins/sfDoctrineGuardPlugin/data/fixtures/fixtures.yml.sample data/fixtures/sfGuard.yml symfony doctrine:data-load frontend # replace frontend with the name of one of your application
Enable one or more modules in your settings.yml (optional), (*13)
For your backend application: sfGuardUser, sfGuardGroup, sfGuardPermission, (*14)
all:
.settings:
enabled_modules: [default, sfGuardGroup, sfGuardUser, sfGuardPermission]
PLEASE NOTE: these modules are NOT SECURED by default, because we can't guess what you want your policies to be. Please read the "Secure your application" section below., (*15)
For your frontend application: sfGuardAuth, (*16)
all:
.settings:
enabled_modules: [default, sfGuardAuth]
Do not secure sfGuardAuth, it is the module that allows the user to log in., (*17)
Clear you cache, (*18)
symfony cc
Optionally add the "Remember Me" filter to filters.yml above the security filter:, (*19)
remember_me: class: sfGuardRememberMeFilter security: ~
The 5.0.x series adds several new tables, adds columns to existing tables and changes the names of all of the relations in the schema., (*20)
This requires changes of two kinds: database schema changes and, in some cases, changes to your code. We'll look at each of these issues in turn., (*21)
There are three basic changes in the schema:, (*22)
sfGuardUser table, which now contains first_name, last_name and email_address informationsfGuardForgotPassword table used to verify password reset requests and account creation requestsIt would be handy to use Doctrine's generate-migrations-diff task to update the schema, but unfortunately while it is a powerful tool it cannot figure out how to change the ID columns to 8 bytes without foreign key errors. You can write a migration yourself or just use SQL ALTER TABLE statements. If you choose to do so, you will need to drop the foreign key indexes first (never the columns of course, just the indexes), alter the ID column types, and then create the foreign key indexes again. We recommend locking the database while doing so., (*23)
You can also leave the types of the IDs alone in your existing database. That is a great deal easier. If you choose this approach, make sure you create the new sfGuardForgotPassword table with 4-byte integers, just like your old tables, as explained below., (*24)
There are three new columns in the sf_guard_user table. You can add these with the following SQL statements:, (*25)
ALTER TABLE sf_guard_user ADD COLUMN first_name varchar(255) DEFAULT NULL; ALTER TABLE sf_guard_user ADD COLUMN last_name varchar(255) DEFAULT NULL; ALTER TABLE sf_guard_user ADD COLUMN email_address varchar(255) DEFAULT '';
Next you should specify that the email address must be unique. This poses a problem if your users do not currently have an email address field at all in your existing system (for instance, you have no profile table, or there is no email address in it). You can work around it this way as a temporary solution:, (*26)
UPDATE sf_guard_user SET email_address = username;
This ensures a unique setting although it does not actually provide a useful email address. If you have a profile table with email addresses, a better idea is to import your email addresses from there:, (*27)
UPDATE sf_guard_user,sf_guard_profile SET sf_guard_user.email_address = sf_guard_profile.email_address WHERE sf_guard_user.id = sf_guard_profile.id;
Now you are ready to index the column and make it unique:, (*28)
ALTER TABLE sf_guard_user ADD UNIQUE KEY `email_address` (`email_address`);
You can do this with the following SQL code., (*29)
If you wish to stick with 4-byte IDs:, (*30)
CREATE TABLE sf_guard_forgot_password (id INT AUTO_INCREMENT, user_id INT NOT NULL, unique_key VARCHAR(255), expires_at DATETIME NOT NULL, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, INDEX user_id_idx (user_id), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci ENGINE = INNODB;
If you have upgraded your IDs:, (*31)
CREATE TABLE sf_guard_forgot_password (id BIGINT AUTO_INCREMENT, user_id BIGINT NOT NULL, unique_key VARCHAR(255), expires_at DATETIME NOT NULL, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, INDEX user_id_idx (user_id), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci ENGINE = INNODB;
If you have not migrated your database schema yet, DO THAT FIRST (see above). Otherwise you lose the option of using Doctrine migrations., (*32)
After updating your schema you will also need to update your code to account for the changes., (*33)
First rebuild your model, form and filter base classes. This will not damage any custom code in your own model classes, as long as you followed standard practice and left the Base classes alone:, (*34)
./symfony doctrine:build --all-classes
Second, check your Doctrine code for places where you use the relations that are defined for sfGuardUser, sfGuardGroup, etc. The names of these relations have been changed for convenience and to follow Symfony best practices., (*35)
The most frequently used relations that have changed are:, (*36)
$group->users is now $group->Users (uppercase) $group->permissions is now $group->Permissions (uppercase) $user->groups is now $user->Groups (uppercase) $user->permissions is now $user->Permissions (uppercase), (*37)
The less commonly used relations on sfGuardUserPermission and sfGuardGroupPermission have changed as well. They are capitalized and they do not have an sfGuard prefix. Those who sometimes write custom queries to locate users with particular privileges need to be aware of this., (*38)
To secure a symfony application:, (*39)
Enable the module sfGuardAuth in settings.yml, (*40)
all:
.settings:
enabled_modules: [..., sfGuardAuth]
Change the default login and secure modules in settings.yml, (*41)
login_module: sfGuardAuth login_action: signin secure_module: sfGuardAuth secure_action: secure
Change the parent class in myUser.class.php, (*42)
php
class myUser extends sfGuardSecurityUser
{
}, (*43)
Optionally add the following routing rules to routing.yml, (*44)
sf_guard_signin:
url: /login
param: { module: sfGuardAuth, action: signin }
sf_guard_signout:
url: /logout
param: { module: sfGuardAuth, action: signout }
sf_guard_register:
url: /register
param: { module: sfGuardRegister, action: index }
sf_guard_forgot_password:
url: /forgot_password
param: { module: sfGuardForgotPassword, action: index }
sf_guard_forgot_password_change:
url: /forgot_password/:unique_key
class: sfDoctrineRoute
options: { model: sfGuardForgotPassword, type: object }
param: { module: sfGuardForgotPassword, action: change }
requirements:
sf_method: [get, post]
You can customize the url parameter of each route.
N.B.: You must have a @homepage routing rule (used when a user sign out), (*45)
These routes are automatically registered by the plugin if the module sfGuardAuth
is enabled unless you defined sf_guard_plugin_routes_register to false
in the app.yml configuration file:, (*46)
all:
sf_guard_plugin:
routes_register: false
Secure some modules or your entire application in security.yml, (*47)
default: is_secure: true
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., (*48)
If you do NOT secure your entire site by default, then make sure you DO secure the sfGuardUser, sfGuardGroup and sfGuardPermission modules in particular! Otherwise anonymous users can create users, groups and permissions at any time. This is a common oversight on sfDoctrineGuardPlugin sites., (*49)
To be able to manage your users, permissions and groups, sfDoctrineGuardPlugin comes
with 3 modules that can be integrated in your backend application.
These modules are auto-generated thanks to the symfony admin generator., (*50)
Enable the modules in settings.yml, (*51)
all:
.settings:
enabled_modules: [..., sfGuardGroup, sfGuardPermission, sfGuardUser]
Remember to secure these modules via security.yml if you are not securing your entire site. Otherwise anonymous users can create and delete users, (*52)
Access the modules with the default route sf_guard_user:, (*53)
http://www.example.com/backend.php/guard/users, (*54)
Some site administrators will wish to allow members of the public to apply for accounts. Beginning in 5.0.0 this feature is available in sfDoctrineGuardPlugin., (*55)
To enable the feature you must enable the sfGuardRegister module, then provide users with a link to the sfGuardRegister/index action., (*56)
[TODO: flesh this out further] [TODO: document the forgot password feature], (*57)
By default, sfGuardAuth module comes with 2 very simple templates:, (*58)
signinSuccess.phpsecureSuccess.phpIf you want to customize one of these templates:, (*59)
Create a sfGuardAuth module in your application (don't use the
init-module task, just create a sfGuardAuth directory), (*60)
Create a template with the name of the template you want to customize in
the sfGuardAuth/templates directory, (*61)
symfony now renders your template instead of the default one, (*62)
sfGuardAuth module actionsIf you want to customize or add methods to the sfGuardAuth:, (*63)
Create a sfGuardAuth module in your application, (*64)
Create an actions.class.php file in your actions directory that inherit
from BasesfGuardAuthActions (don't forget to include the BasesfGuardAuthActions
as it can't be autoloaded by symfony), (*65)
```php require_once(sfConfig::get('sf_plugins_dir').'/sfDoctrineGuardPlugin/modules/sfGuardAuth/lib/BasesfGuardAuthActions.class.php');, (*66)
class sfGuardAuthActions extends BasesfGuardAuthActions
{
public function executeNewAction()
{
return $this->renderText('This is a new sfGuardAuth action.');
}
}
```, (*67)
sfGuardSecurityUser classThis class inherits from Symfony's sfBasicSecurityUser class and is
used for the user object in your symfony application.
(Remember that you changed the myUser base class earlier.), (*68)
To access it, you can use the standard $this->getUser() in your actions
or $sf_user in your templates., (*69)
sfGuardSecurityUser adds some useful methods:, (*70)
signIn() and signOut() methodsgetGuardUser(), which returns the sfGuardUser objectsfGuardUser objectFor example, to get the current username:, (*71)
```php $this->getUser()->getGuardUser()->getUsername(), (*72)
// or via the proxy method $this->getUser()->getUsername()
```, (*73)
To prevent chicken and egg problems, sfDoctrineGuardPlugin has the concept of a "superadmin." A user that is a superadmin
bypasses all credential checks., (*74)
The superadmin flag cannot be set via the sfGuardUser admin module, you must set the flag
directly in the database or use the provided Symfony task:, (*75)
symfony guard:promote admin
sfDoctrineGuardPlugin comes with a validator that you can use in your modules:
sfGuardUserValidator., (*76)
This validator is used by the sfGuardAuth module to validate the username and
password before signing the user in., (*77)
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:, (*78)
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 return true
or false. Here is a template for such a function:, (*79)
php
function checkLDAPPassword($username, $password)
{
$user = LDAP::getUser($username);
if ($user->checkPassword($password))
{
return true;
}
else
{
return false;
}
}, (*80)
By default, passwords are stored as a sha1() hash. But you can change this
with any callable in app.yml:, (*81)
all:
sf_guard_plugin:
algorithm_callable: [MyCryptoClass, MyCryptoMethod]
or:, (*82)
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., (*83)
By default, the "Remember Me" feature creates a cookie named sfRemember
that will last 15 days. You can change this behavior in app.yml:, (*84)
all:
sf_guard_plugin:
remember_key_expiration_age: 2592000 # 30 days in seconds
remember_cookie_name: myAppRememberMe
sfGuardAuth redirect handlingIt is possible to redirect the user to his profile after a successful login, or to a particular page on logout., (*85)
You can change the redirect settings in app.yml:, (*86)
all:
sf_guard_plugin:
success_signin_url: @my_route?param=value # the plugin uses the referer as default
success_signout_url: module/action # the plugin uses the referer as default
Identity management plugin for symfony
MIT
Identity management plugin for symfony
MIT
Identity management plugin for symfony
MIT
Identity management plugin for symfony
MIT
Identity management plugin for symfony
MIT
Identity management plugin for symfony
MIT