You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 2, 2020. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+19-15Lines changed: 19 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@
6
6
7
7
### Usage
8
8
9
-
`cbguard` lets us lock down methods to logged in users and users with specific permissions using one annotation — `secured`. Just sticking the secured annotation on a handler or action is enough to require a user to log in before executing those events.
9
+
`cbguard` lets us lock down methods to logged in users and users with specific permissions using one annotation — `secured`. Just sticking the secured annotation on a handler or action is enough to require a user to log in before executing those events.
10
10
11
11
Here's an example of how to lock down an entire handler:
12
12
@@ -36,7 +36,7 @@ component {
36
36
}
37
37
```
38
38
39
-
You can further lock down handlers and actions to a list of specific permissions. If specified, the logged in user must have one of the permissions in the list specified.
39
+
You can further lock down handlers and actions to a list of specific permissions. If specified, the logged in user must have one of the permissions in the list specified.
40
40
41
41
```cfc
42
42
component secured="admin" {
@@ -64,7 +64,7 @@ component {
64
64
}
65
65
```
66
66
67
-
Individual actions can be secured in the same way. Above, the `show` action requires the logged in user to have either the `admin` or the `reviews_posts` permission.
67
+
Individual actions can be secured in the same way. Above, the `show` action requires the logged in user to have either the `admin` or the `reviews_posts` permission.
68
68
69
69
These two approaches can be combined and both handler and actions can be secured together:
70
70
@@ -118,7 +118,7 @@ public void function authorize( required any permissions, struct additionalArgs
118
118
In all cases `permissions` can be either a string, a list of strings, or an array of strings.
119
119
120
120
In the case of `authorize` the `errorMessage` replaces the thrown error message
121
-
in the `NotAuthorized`. exception. It can also be a closure that takes the following shape:
121
+
in the `NotAuthorized`. exception. It can also be a closure that takes the following shape:
122
122
123
123
```cfc
124
124
string function errorMessage( array permissions, any user, struct additionalArgs );
@@ -127,14 +127,14 @@ string function errorMessage( array permissions, any user, struct additionalArgs
127
127
#### Defining Custom Guards
128
128
129
129
While handling all of your guard clauses inside the `hasPermission` method on your user
130
-
works fine, you may want to define a different way to handle permissions. You
131
-
can do this by declaring custom guards using the `guard.define` method. Here's the signature:
130
+
works fine, you may want to define a different way to handle permissions. You
131
+
can do this by declaring custom guards using the `guard.define` method. Here's the signature:
132
132
133
133
```cfc
134
134
public Guard function define( required string name, required any callback );
135
135
```
136
136
137
-
The `name` will match against a permission name. If it matches, the guard is
137
+
The `name` will match against a permission name. If it matches, the guard is
138
138
called instead of calling `hasPermission` on the `User` model. (You can always
139
139
call `hasPermission` on the `User` inside your guard callback if you need.)
140
140
@@ -149,7 +149,7 @@ public boolean function authorize( required any user, struct additionalArgs = {}
149
149
```
150
150
151
151
Using this approach, you can define custom guards anywhere in your application:
152
-
`config/ColdBox.cfc`, `ModuleConfig.cfc` of your custom modules, etc. The
152
+
`config/ColdBox.cfc`, `ModuleConfig.cfc` of your custom modules, etc. The
153
153
`Guard` component is registered as a singleton, so it will keep track of all the
154
154
guards registered, even from different sources.
155
155
@@ -161,7 +161,7 @@ public Guard function removeDefinition( required string name );
161
161
162
162
### Redirects
163
163
164
-
When a user is denied access to a action, an event of your choosing is executed instead. There are four keys that can be set in the `moduleSettings` struct that all come with good defaults.
164
+
When a user is denied access to a action, an event of your choosing is executed instead. There are four keys that can be set in the `moduleSettings` struct that all come with good defaults.
This is the event that is executed when the user is not logged in and is attempting to execute a secured action via ajax (`event.isAjax()`), whether or not that handler or action has permissions. By default, this will execute the same action that is configured for `authenticationOverrideEvent`.
176
+
This is the event that is executed when the user is not logged in and is attempting to execute a secured action via ajax (`event.isAjax()`), whether or not that handler or action has permissions. By default, this will execute the same action that is configured for `authenticationOverrideEvent`.
177
177
178
178
4.`authorizationAjaxOverrideEvent` (Default: same as `authorizationOverrideEvent`)
179
179
180
180
This is the event that is executed when the user is logged in and is attempting to execute a secured action via ajax (`event.isAjax()`) but does not have the requisite permissions. By default, this will execute the same action that is configured for `authorizationOverrideEvent`.
181
181
182
+
### \_securedUrl
183
+
184
+
When an override event is used, the url the user was trying to access is stored in the `flash` scope as `_securedUrl`.
185
+
You can make use of this in your login actions to send the user back where they intended after logging in.
182
186
183
187
### Setup
184
188
@@ -234,12 +238,11 @@ moduleSettings = {
234
238
};
235
239
```
236
240
237
-
The default `authenticationService` for `cbguard` is `AuthenticationService@cbauth`. `cbauth` follows the `AuthenticationServiceInterface` out of the box.
238
-
241
+
The default `authenticationService` for `cbguard` is `AuthenticationService@cbauth`. `cbauth` follows the `AuthenticationServiceInterface` out of the box.
239
242
240
243
### config/ColdBox.cfc Settings
241
244
242
-
You can change the method names called on the `AuthenticationService` and the returned `User` if you need to. We highly discourage this use case, as it makes it harder to utilize the `cbguard` conventions across projects. However, should the need arise, you can modify the method names as follows:
245
+
You can change the method names called on the `AuthenticationService` and the returned `User` if you need to. We highly discourage this use case, as it makes it harder to utilize the `cbguard` conventions across projects. However, should the need arise, you can modify the method names as follows:
243
246
244
247
```cfc
245
248
moduleSettings = {
@@ -271,10 +274,9 @@ moduleSettings = {
271
274
`relocate` refers to calling `relocate` on the controller. The user will be redirected to the new page.
272
275
`override` refers to `event.overrideEvent`. This will not redirect but simply change the running event.
273
276
274
-
275
277
### Module Overrides
276
278
277
-
All of the `cbguard` settings can be overriden inside a module. This allows modules, such as an API module, to provide
279
+
All of the `cbguard` settings can be overriden inside a module. This allows modules, such as an API module, to provide
278
280
their own authentication services as well as redirect events.
279
281
280
282
To specify some overrides, create a `cbguard` struct in your desired module's `settings` in that module's `ModuleConfig.cfc`.
@@ -327,7 +329,9 @@ component secured {
327
329
```
328
330
329
331
### Override Order
332
+
330
333
cbguard will process your authorization and authentication failures in the following order:
334
+
331
335
1. Inline handler methods (`onAuthenticationFailure` & `onAuthorizationFailure` within your handlers).
332
336
2. cbguard settings in the ModuleConfig of the handler's module. (Overrides in `modules_app/api/ModuleConfig.cfc` when the handler is in the module, i.e. `modules_app/api/handlers/Main.cfc`.)
333
337
3. Overrides in `config/ColdBox.cfc` using `moduleSettings`.
0 commit comments