You are viewing the documentation for Play 1. The documentation for Play 2 is here.

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 @With annotation.

Module set-up

Enable the Secure module for the application

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

require:
    - play -> secure

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

Import default Secure routes

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

# Import Secure routes
*      /                module:secure

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

Protecting a controller

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

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

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

Customizing the authentication mechanism

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.

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);
    }
}

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

Retrieving the connected user

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

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

Adding authorization checks

Controller annotation

You can use the @Check 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:

@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 @Check annotation either on the controller class:

@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.

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;
        }
    }    
}

Template tag

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:

#{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.

Commands

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.

Documentation