Skip to content

Commit 0bc8358

Browse files
matreimatrei
committed
docs: update requestmap docs
1 parent 9f90f67 commit 0bc8358

File tree

2 files changed

+55
-53
lines changed

2 files changed

+55
-53
lines changed

‎plugin-core/docs/src/docs/domainClasses/requestmapClass.adoc‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,36 +18,37 @@ under the License.
1818
////
1919

2020
[[requestmapClass]]
21-
=== Requestmap Class
21+
=== Requestmap Domain Class
2222

23-
Optionally, use this class to store request mapping entries in the database instead of defining them with annotations or in `application.groovy`. This option makes the class configurable at runtime; you can add, remove and edit rules without restarting your application.
23+
Create and use a domain class to store request mapping entries in the database instead of defining them with annotations
24+
or in `application.groovy`. This option makes the rules configurable at runtime; you can add, remove and edit rules
25+
without restarting your application.
2426

2527
.Requestmap class configuration options
2628
[cols="30,30,40"]
2729
|====================
2830
| *Property* | *Default Value* | *Meaning*
2931

3032
|requestMap.className
31-
|_none_
32-
|requestmap class name
33+
|_none_ - set to your implementation
34+
|requestmap domain class
3335

3436
|requestMap.urlField
35-
|"`url`"
37+
|"url"
3638
|URL pattern property name
3739

3840
|requestMap.configAttributeField
39-
|"`configAttribute`"
41+
|"configAttribute"
4042
|authority pattern property name
4143

4244
|requestMap.httpMethodField
43-
|"`httpMethod`"
45+
|"httpMethod"
4446
|HTTP method property name (optional, does not have to exist in the class if you don't require URL/method security)
4547
|====================
4648

47-
Assuming you choose `com.mycompany.myapp` as your package, and `Requestmap` as your class name, you'll generate this class:
49+
Assuming you choose `com.mycompany.myapp` as your package, and `SecurityMapping` as your class name, you'll generate this class:
4850

4951
[source, groovy]
50-
.`Requestmap.groovy`
5152
----
5253
package com.mycompany.myapp
5354
@@ -60,7 +61,7 @@ import grails.compiler.GrailsCompileStatic
6061
@GrailsCompileStatic
6162
@EqualsAndHashCode(includes=['configAttribute', 'httpMethod', 'url'])
6263
@ToString(includes=['configAttribute', 'httpMethod', 'url'], cache=true, includeNames=true, includePackage=false)
63-
class RequestMap implements Serializable {
64+
class SecurityMapping implements Serializable {
6465
6566
private static final long serialVersionUID = 1
6667
@@ -69,15 +70,15 @@ class RequestMap implements Serializable {
6970
String url
7071
7172
static constraints = {
72-
configAttribute blank: false
73-
httpMethod nullable: true
74-
url blank: false, unique: 'httpMethod'
73+
configAttribute(blank: false)
74+
httpMethod(nullable: true)
75+
url(blank: false, unique: 'httpMethod')
7576
}
7677
7778
static mapping = {
78-
cache true
79+
cache(true)
7980
}
8081
}
8182
----
8283

83-
To use Requestmap entries to guard URLs, see <<requestmapInstances>>.
84+
To use database entries to guard URLs, see <<requestmapInstances>>.

‎plugin-core/docs/src/docs/requestMappings/requestmapInstances.adoc‎

Lines changed: 39 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -18,29 +18,30 @@ under the License.
1818
////
1919

2020
[[requestmapInstances]]
21-
=== Requestmap Instances Stored in the Database
21+
=== Request Mappings Stored in the Database
2222

23-
With this approach you use the `Requestmap` domain class to store mapping entries in the database. `Requestmap` has a `url` property that contains the secured URL pattern and a `configAttribute` property containing a comma-delimited list of required roles, SpEL expressions, and/or tokens such as `IS_AUTHENTICATED_FULLY`, `IS_AUTHENTICATED_REMEMBERED`, and `IS_AUTHENTICATED_ANONYMOUSLY`.
23+
With this approach you create and use a domain class to store security mapping entries in the database.
2424

25-
To use `Requestmap` entries, specify `securityConfigType="Requestmap"`:
25+
The domain class must have the following properties:
2626

27-
[source,groovy]
28-
.Listing {counter:listing}. Specifying `securityConfigType` as "`Requestmap`"
29-
----
30-
grails.plugin.springsecurity.securityConfigType = "Requestmap"
31-
----
27+
* `url` - the secured URL pattern
28+
* `httpMethod` - the http method for which the rule applies (or null for all methods)
29+
* `configAttribute` - containing a comma-delimited list of required roles,
30+
SpEL expressions, and/or tokens such as `IS_AUTHENTICATED_FULLY`, `IS_AUTHENTICATED_REMEMBERED`,
31+
and `IS_AUTHENTICATED_ANONYMOUSLY`
3232

33-
A domain class must also be specified for the `Requestmap`:
33+
To use database-backed url security mappings, use the following configuration:
3434

3535
[source,groovy]
36-
.Listing {counter:listing}. Specifying `requestMap.className` with a domain class
36+
.Listing {counter:listing}. Configuring database-backed url security rules
3737
----
38-
grails.plugin.springsecurity.requestMap.className = "com.foo.bar.Requestmap"
38+
grails.plugin.springsecurity.securityConfigType = 'Requestmap'
39+
grails.plugin.springsecurity.requestMap.className = 'com.foo.bar.SecurityMapping'
3940
----
4041

41-
An example `Requestmap` domain class:
42+
An example request map domain class:
4243
[source, groovy]
43-
.`Requestmap.groovy`
44+
.Listing {counter:listing}. An example request map domain class
4445
----
4546
package com.foo.bar
4647
@@ -50,8 +51,8 @@ import groovy.transform.EqualsAndHashCode
5051
import groovy.transform.ToString
5152
5253
@EqualsAndHashCode(includes=['configAttribute', 'httpMethod', 'url'])
53-
@ToString(includes=['configAttribute', 'httpMethod', 'url'], cache=true, includeNames=true, includePackage=false)
54-
class Requestmap implements Serializable {
54+
@ToString(includes=['configAttribute', 'httpMethod', 'url'], cache = true, includeNames = true, includePackage = false)
55+
class SecurityMapping implements Serializable {
5556
5657
private static final long serialVersionUID = 1
5758
@@ -60,67 +61,67 @@ class Requestmap implements Serializable {
6061
String url
6162
6263
static constraints = {
63-
configAttribute nullable: false, blank: false
64-
httpMethod nullable: true
65-
url nullable: false, blank: false, unique: 'httpMethod'
64+
configAttribute(nullable: false, blank: false)
65+
httpMethod(nullable: true)
66+
url(nullable: false, blank: false, unique: 'httpMethod')
6667
}
6768
6869
static mapping = {
69-
cache true
70+
cache(true)
7071
}
7172
}
7273
----
7374

74-
You create `Requestmap` entries as you create entries in any Grails domain class:
75+
You create request map entries as you create entries in any Grails domain class:
7576

7677
[source,groovy]
77-
.Listing {counter:listing}. Creating `Requestmap` entries
78+
.Listing {counter:listing}. Creating request map entries
7879
----
7980
for (String url in [
8081
'/', '/error', '/index', '/index.gsp', '/**/favicon.ico', '/shutdown',
8182
'/assets/**', '/**/js/**', '/**/css/**', '/**/images/**',
8283
'/login', '/login.*', '/login/*',
8384
'/logout', '/logout.*', '/logout/*']) {
84-
new Requestmap(url: url, configAttribute: 'permitAll').save()
85+
new SecurityMapping(url: url, configAttribute: 'permitAll').save()
8586
}
8687
87-
new Requestmap(url: '/profile/**', configAttribute: 'ROLE_USER').save()
88-
new Requestmap(url: '/admin/**', configAttribute: 'ROLE_ADMIN').save()
89-
new Requestmap(url: '/admin/role/**', configAttribute: 'ROLE_SUPERVISOR').save()
90-
new Requestmap(url: '/admin/user/**',
88+
new SecurityMapping(url: '/profile/**', configAttribute: 'ROLE_USER').save()
89+
new SecurityMapping(url: '/admin/**', configAttribute: 'ROLE_ADMIN').save()
90+
new SecurityMapping(url: '/admin/role/**', configAttribute: 'ROLE_SUPERVISOR').save()
91+
new SecurityMapping(url: '/admin/user/**',
9192
configAttribute: 'ROLE_ADMIN,ROLE_SUPERVISOR').save()
92-
new Requestmap(url: '/login/impersonate',
93+
new SecurityMapping(url: '/login/impersonate',
9394
configAttribute: 'ROLE_SWITCH_USER,IS_AUTHENTICATED_FULLY').save()
9495
springSecurityService.clearCachedRequestmaps()
9596
----
9697

97-
The `configAttribute` value can have a single value or have multiple comma-delimited values. In this example only users with `ROLE_ADMIN` or `ROLE_SUPERVISOR` can access `/admin/user/pass:[**]` urls, and only users with `ROLE_SWITCH_USER` can access the switch-user url (`/login/impersonate`) and in addition must be authenticated fully, i.e. not using a remember-me cookie. Note that when specifying multiple roles, the user must have at least one of them, but when combining `IS_AUTHENTICATED_FULLY`, `IS_AUTHENTICATED_REMEMBERED`, or `IS_AUTHENTICATED_ANONYMOUSLY` with one or more roles means the user must have one of the roles and satisty the `IS_AUTHENTICATED` rule.
98+
The `configAttribute` value can have a single value or have multiple comma-delimited values. In this example only users with `ROLE_ADMIN` or `ROLE_SUPERVISOR` can access `/admin/user/pass:[**]` urls, and only users with `ROLE_SWITCH_USER` can access the switch-user url (`/login/impersonate`) and in addition must be authenticated fully, i.e. not using a remember-me cookie. Note that when specifying multiple roles, the user must have at least one of them, but when combining `IS_AUTHENTICATED_FULLY`, `IS_AUTHENTICATED_REMEMBERED`, or `IS_AUTHENTICATED_ANONYMOUSLY` with one or more roles means the user must have one of the roles and satisfy the `IS_AUTHENTICATED` rule.
9899

99-
Unlike the `application.groovy` Map approach (<<configGroovyMap>>), you do not need to revise the `Requestmap` entry order because the plugin calculates the most specific rule that applies to the current request.
100+
Unlike the `application.groovy` map approach (<<configGroovyMap>>), you do not need to revise the request map entry order because the plugin calculates the most specific rule that applies to the current request.
100101

101-
==== Requestmap Cache
102+
==== Request Map Cache
102103

103-
`Requestmap` entries are cached for performance, but caching affects runtime configurability. If you create, edit, or delete an instance, the cache must be flushed and repopulated to be consistent with the database. You can call `springSecurityService.clearCachedRequestmaps()` to do this. For example, if you create a `RequestmapController` the `save` action should look like this (and the update and delete actions should similarly call `clearCachedRequestmaps()`):
104+
Request map entries are cached for performance, but caching affects runtime configurability. If you create, edit, or delete an instance, the cache must be flushed and repopulated to be consistent with the database. You can call `springSecurityService.clearCachedRequestmaps()` to do this. For example, if you create a `RequestSecurityRuleController` the `save` action should look like this (and the update and delete actions should similarly call `clearCachedRequestmaps()`):
104105

105106
[source,groovy]
106107
.Listing {counter:listing}. Calling `clearCachedRequestmaps()`
107108
----
108-
class RequestmapController {
109+
class SecurityMappingController {
109110
110111
def springSecurityService
111112
112-
...
113+
//...
113114
114-
def save(Requestmap requestmap) {
115-
if (!requestmap.save(flush: true)) {
116-
render view: 'create', model: [requestmapInstance: requestmap]
115+
def save(SecurityMapping mapping) {
116+
if (!mapping.save(flush: true)) {
117+
render(view: 'create', model: [instance: mapping])
117118
return
118119
}
119120
120121
springSecurityService.clearCachedRequestmaps()
121122
122-
flash.message = ...
123-
redirect action: 'show', id: requestmap.id
123+
flash.message = 'Mapping saved'
124+
redirect(action: 'show', id: mapping.id)
124125
}
125126
}
126127
----

0 commit comments

Comments
 (0)