-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
305 lines (205 loc) · 9.32 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
# sfGuardDoctrine plugin (for symfony 1.3) #
The `sfDoctrineGuardPlugin` 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 (via a package)
symfony plugin:install sfDoctrineGuardPlugin
* Install the plugin (via a Subversion checkout)
svn co http//svn.symfony-project.com/plugins/sfDoctrineGuardPlugin/trunk plugins/sfDoctrineGuardPlugin
* Activate the plugin in the `config/ProjectConfiguration.class.php`
[php]
class ProjectConfiguration extends sfProjectConfiguration
{
public function setup()
{
$this->enablePlugins(array(
'sfDoctrinePlugin',
'sfDoctrineGuardPlugin',
'...'
));
}
}
* Rebuild your model
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):
symfony doctrine:insert-sql
or do everything with one command
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`
* Load default fixtures (optional - it creates a superadmin user)
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)
* For your backend application: sfGuardUser, sfGuardGroup, sfGuardPermission
all:
.settings:
enabled_modules: [default, sfGuardGroup, sfGuardUser, sfGuardPermission]
* For your frontend application: sfGuardAuth
all:
.settings:
enabled_modules: [default, sfGuardAuth]
* Clear you cache
symfony cc
* Optionally add the "Remember Me" filter to `filters.yml` above the security filter:
[yml]
remember_me:
class: sfGuardRememberMeFilter
security: ~
### 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 `sf_guard_plugin_routes_register` to false
in the `app.yml` configuration file:
all:
sf_guard_plugin:
routes_register: false
* Secure some modules or your entire application in `security.yml`
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.
## Manage your users, permissions and groups ##
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.
* 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 (don't use the
`init-module` task, just create a `sfGuardAuth` directory)
* Create a template with the name of the template you want to customize in
the `sfGuardAuth/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` (don't forget to include the `BasesfGuardAuthActions`
as it can't be autoloaded by symfony)
<?php
require_once(sfConfig::get('sf_plugins_dir').'/sfDoctrineGuardPlugin/modules/sfGuardAuth/lib/BasesfGuardAuthActions.class.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 changed the `myUser` base class earlier)
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 ##
`sfDoctrineGuardPlugin` 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 guard:promote admin
## Validators ##
`sfDoctrineGuardPlugin` 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.
## 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.
## Change the name or expiration period of the "Remember Me" cookie ##
By default, the "Remember Me" feature creates a cookie named `sfRemember`
that will last 15 days. You can change this behavior in `app.yml`:
all:
sf_guard_plugin:
remember_key_expiration_age: 2592000 # 30 days in seconds
remember_cookie_name: myAppRememberMe
## Customize `sfGuardAuth` redirect handling ##
If you want to redirect the user to his profile after a success login or
define a logout site.
You can change the redirect values in `app.yml`:
all:
sf_guard_plugin:
success_signin_url: @my_route?param=value # the plugin use the referer as default
success_signout_url: module/action # the plugin use the referer as default