[[usingControllerAnnotations]]
=== Using Controller Annotations to Secure URLs

==== 1. Create your Grails application.

....
$ grails create-app bookstore
$ cd bookstore
....

==== 2. "`Install`" the plugin by adding it to build.gradle

[source,groovy]
[subs="attributes"]
----
dependencies {
   ...
   compile 'org.grails.plugins:spring-security-core:{project-version}'
   ...
}
----

Run the compile command to resolve dependencies and ensure everything is correct:

....
$ grails compile
....

==== 3. Create the User and Role domain classes.

....
$ grails s2-quickstart com.mycompany.myapp User Role
....

You can choose your names for your domain classes and package; these are just examples.

[NOTE]
====
Depending on your database, some domain class names might not be valid, especially those relating to security. Before you create names like "`User`" or "`Group`", make sure they are not reserved keywords in your database, or escape the name with backticks in the `mapping` block, e.g.

[source,groovy]
----
static mapping = {
   table '`user`'
}
----
====

If you are using Spring Core version 3.1.2 or later and GORM 6.0.10 or later, the script creates this User class:

[source, groovy]
.`grails-app/domain/com/mycompany/myapp/User.groovy`
----
include::../code/s2-quickstart/grails-app/domain/com/mycompany/myapp/User.groovy[]
----

and a password encoder listener to manage password encoding:

[source, groovy]
.`grails-app/conf/spring/resources.groovy`
----
include::../code/s2-quickstart/grails-app/conf/spring/resources.groovy[]
----

[source, groovy]
.`src/main/groovy/com/mycompany/myapp/UserPasswordEncoderListener.groovy`
----
include::../code/s2-quickstart/src/main/groovy/com/mycompany/myapp/UserPasswordEncoderListener.groovy[]
----

Previous versions of the plugin's script manage the password encoding directly in domain class:

[source, groovy]
.`grails-app/domain/com/mycompany/myapp/User.groovy`
----
include::../code/s2-quickstart-old/grails-app/domain/com/mycompany/myapp/User.groovy[]
----

include::../domainClasses/gormAutowire.adoc[]

`s2-quickstart` script generates this Role too:

[source, groovy]
.`Role.groovy`
----
include::../code/s2-quickstart/grails-app/domain/com/mycompany/myapp/Role.groovy[]
----

and a domain class that maps the many-to-many join class, `UserRole`:

[source, groovy]
.`UserRole.groovy`
----
include::../code/s2-quickstart/grails-app/domain/com/mycompany/myapp/UserRole.groovy[]
----

[NOTE]
====
These generated files are not part of the plugin - these are your application files.
They are examples to get you started, so you can edit them as you please.
They contain the minimum needed for the plugin's default implementation of the Spring Security `UserDetailsService`
(which like everything in the plugin is customizable - see <<userDetailsService>>).
====

The script has edited (or created) `grails-app/conf/application.groovy` and added the configuration for your domain classes. Make sure that the changes are correct.

While you're looking at `application.groovy`, add this config override to make the sample app easier to work with:

[source,groovy]
----
grails.plugin.springsecurity.logout.postOnly = false
----

[WARNING]
====
By default only POST requests can be used to logout; this is a very sensible default and shouldn't be changed in most cases. However to keep things simple for this tutorial we'll change it (using the `logout.postOnly` config override above) to avoid having to create a GSP form that POSTs to /logout.
====

The plugin has no support for CRUD actions or GSPs for your domain classes; the `spring-security-ui` plugin supplies a UI for those. So for now you will create roles and users in `grails-app/init/BootStrap.groovy`. (See step 7.)

==== 4. Create a controller that will be restricted by role.

....
$ grails create-controller com.mycompany.myapp.Secure
....

This command creates `grails-app/controllers/com/mycompany/myapp/SecureController.groovy`. Add some output so you can verify that things are working:

[source, groovy]
.`SecureController.groovy`
----
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=packageImport]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=class]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=index]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=classClose]
----

==== 5. Edit grails-app/init/BootStrap.groovy to add a test user.

[source,groovy]
.`BootStrap.groovy`
----
include::../code/s2-quickstart/grails-app/init/com/mycompany/myapp/BootStrap.groovy[]
----

Some things to note about the preceding `BootStrap.groovy`:

* The example does not use a traditional GORM many-to-many mapping for the User pass:[&lt;==&gt;] Role relationship; instead you are mapping the join table with the `UserRole` class. This performance optimization helps significantly when many users have one or more common roles.
* We explicitly flush (using `withSession`) because `BootStrap` does not run in a transaction or OpenSessionInView.

==== 6. Start the server.

....
$ grails run-app
....

==== 7. Verify that you cannot access the page yet.

Before you secure the page, navigate to http://localhost:8080/secure to verify that you cannot access the page yet. You will be redirected to the login page, but after a successful authentication (log in with the username and password you used for the test user in BootStrap.groovy) you will see an error page:

....
Sorry, you're not authorized to view this page.
....

This is because with the default configuration, all URLs are denied unless there is an access rule specified.

==== 8. Apply the annotation.

Edit `grails-app/controllers/com/mycompany/myapp/SecureController.groovy` to import the annotation class and apply the annotation to restrict (and grant) access.

[source, groovy]
.`SecureController.groovy`
----
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=packageImport]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=import]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=class]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=methodAnnotation]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=index]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=classClose]
----

or

[source, groovy]
.`SecureController.groovy`
----
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=packageImport]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=import]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=securedAnnotation]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=class]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=index]
include::../code/s2-quickstart/grails-app/controllers/com/mycompany/myapp/SecureController.groovy[tag=classClose]
----


You can annotate the entire controller or individual actions. In this case you have only one action, so you can do either.

==== 9. Restart.

Shut down the app and run `grails run-app` again, and navigate again to http://localhost:8080/secure.

This time you should again be able to see the secure page after successfully authenticating.

==== 10. Test the Remember Me functionality.

Check the checkbox, and once you've tested the secure page, close your browser and reopen it. Navigate again the the secure page. Because a cookie is stored, you should not need to log in again. Logout at any time by navigating to http://localhost:8080/logout.

==== 11. Create a CRUD UI.

Optionally, create a CRUD UI to work with users and roles.

===== Run grails generate-all for the domain classes:

....
$ grails generate-all com.mycompany.myapp.User
....

....
$ grails generate-all com.mycompany.myapp.Role
....

Since the User domain class handles password hashing, there are no changes required in the generated controllers.

Be sure to add an `@Secured` annotation to both of the generated controllers to make them accessible.