h1. Secure module

The simple **Secure** module helps you to set-up basic authentication and authorization management in your application. It provides a simple @controllers.Secure@ controller that defines a set of interceptors that you can easily add to your own controllers using the <code>@With</code> annotation.


h2. <a name="setup">Module set-up</a>

h3. <a name="enable">Enable the Secure module for the application</a>

In the @/conf/dependencies.yml@ file, enable the Secure module by adding a line after @require:@

bc. require:
    - play -> secure

Then run the @play dependencies@ command to add the module to your application.


h3. <a name="routes">Import default Secure routes</a>

In the @conf/routes@ file, import the default module routes by adding this line:

bc. # Import Secure routes
*      /                module:secure

p(note). **Note** that it’s not required to use the default routes file. You can also define your own routes, or mix the two.

h2. <a name="controller">Protecting a controller</a>

To protect a controller you just have to annotate it using <code>@With</code>. For example:

bc. @With(Secure.class)
public class Application extends Controller {
    
    public static void index() {
        render();
    }
}

This controller will be automatically protected with the default authentication page.

h2. <a name="custom">Customizing the authentication mechanism</a>

By default, the login page will accept any login/password. To customize it your application has to provide a **Security** provider. Just create a class in the @controllers@ package that extends the @controllers.Secure.Security@ class. Then you can override the @authenticate(String username, String password)@ method.

bc. package controllers;
 
public class Security extends Secure.Security {
    
    static boolean authenticate(String username, String password) {
        User user = User.find("byEmail", username).first();
        return user != null && user.password.equals(password);
    }
}

p(note). **Note** that you can also override other methods to customize how the application should react to authentication events (onAuthenticated, onDisconnected).

h2. <a name="user">Retrieving the connected user</a>

From your application code, you can reuse the Security helper that you’ve just created to retrieve the connected user.

bc. @With(Secure.class)
public class Application extends Controller {
    
    public static void index() {
        String user = Security.connected();
        render(user);
    }
}

h2. <a name="auth">Adding authorization checks</a>

h3. <a name="authcontroller">Controller annotation</a>

You can use the <code>@Check</code> annotation either on controller classes or action methods to tell the Secure module to check that the connected user has the required authorization to call this action.

For example, to restrict an action method to authorized users:

bc. @With(Secure.class)
public class Application extends Controller { 
   …
   
   @Check("administrator")
   public static void delete(Long id) {
       …
   }
}

To restrict all of the action methods in one controller, use the <code>@Check</code> annotation either on the controller class:

bc. @With(Secure.class)
@Check("administrator")
public class Application extends Controller { 
   …
   
   public static void delete(Long id) {
       …
   }
   
   public static void edit(Long id) {
       …
   }
}

By default the secure module will always authorize all checks. You have to customize by overriding one more method in your @Security@ class.

bc. package controllers;
 
public class Security extends Secure.Security {
    …
    
    static boolean check(String profile) {
        User user = User.find("byEmail", connected()).first();
        if ("administrator".equals(profile)) {
            return user.admin;
        }
        else {
            return false;
        }
    }    
}

h3. <a name="authtag">Template tag</a>

You can also use the @secure.check@ tag for authorization checks in templates. This is useful to conditionally display user-interface controls for operations that are protected by controller annotations. For example:

bc. #{secure.check "administrator"}
    <a href="@{delete(item.id)}">Delete</a>
#{/secure.check}

The tag only renders its body for authorised users, so the ‘Delete’ link is only displayed when the user is authorised to execute the @delete@ controller action.

h2. <a name="configuration">Configuration</a>

You can override default settings by adding them to your applications application.conf.

h3. <a name="rememberme">secure.rememberme.duration</a>

The expiration duration of the secure rememberme cookie.

Default: 30d

bc.  secure.rememberme.duration=30d 

h2. <a name="commands">Commands</a>

The Secure module provides a @play secure:override@ that you can use to override the log in page, so you can customize it for your application. This works by copying the corresponding file from the module to a file in your application that will be used instead.

You can abbreviate @play secure:override@ to @play secure:ov@.

h3. <a name="css">CSS override</a>

Use the @play secure:override --css@ command to copy a CSS file to your application that you can edit to customise the log in page look and feel.

h3. <a name="login">Log in template override</a>

Use the @play secure:override --login@ command to copy a log in page view template to your application that overrides the default log in page template.

h3. <a name="layout">Main layout override</a>

Use the @play secure:override --layout@ command to copy a main layout template to your application that overrides the layout used by the log in page.
