Commented routes

If you don't want to add authorization constraints directly into your controllers or use the Authorized routes approach, you can use comments in the routes file.

To get started, you will need to enable DeadboltRouteCommentFilterModule in your application.conf. Note that you also need DeadboltModule.

play {
  modules {
    enabled += be.objectify.deadbolt.java.DeadboltModule
    enabled += be.objectify.deadbolt.java.filters.DeadboltRouteCommentFilterModule
  }
}

This module enables DeadboltRouteCommentFilter, which checks for Deadbolt comments in the route file, once the route has been resolved. The format of these comments is

#deadbolt:<constraint name>:param1[value1]:param2[value2]:paramN[valueN]

NB Note the comments are whitespace-sensitive, and the keys used in the comment are case-sensitive.

Depending on the constraint, various parameters can be specified to change the behaviour. Two parameters are always possible; these are

content The value passed to DeadboltHandler#onAuthFailure if authorization fails.
handler The name of the Deadbolt handler to use for the constraint. This value will be used to look up the handler from the HandlerCache.

Take a simple routes file, which has two routes; one is a static route, the other is dynamic. A static route is simply one that does not contain variables.

#deadbolt:subjectPresent
GET     /profile                    controllers.Application.profile

#deadbolt:composite:name[someCompositeConstraintName]
GET     /view/:foo/:bar             controllers.Application.view(foo: String, bar: String)

Authorization for these routes could be defined as follows - the static route (/profile) only requires that a subject be present, while the dynamic route requires the composite constraint named someCompositeConstraintName is satisfied.

Finally, you need to add DeadboltRouteCommentFilter in your filter definitions. You can read more about how to use filters in Play at https://playframework.com/documentation/2.5.x/JavaHttpFilters.

import javax.inject.Inject;
import be.objectify.deadbolt.java.filters.DeadboltRouteCommentFilter;
import play.http.HttpFilters;
import play.mvc.EssentialFilter;

public class Filters implements HttpFilters {

    // plus any other filters you have
    private final DeadboltRouteCommentFilter deadbolt;

    @Inject
    public Filters(final DeadboltRouteCommentFilter deadbolt) {
        this.deadbolt = deadbolt;
    }

    @Override
    public EssentialFilter[] filters() {
        return new EssentialFilter[]{deadbolt};
    }
}

Subject present

Require a subject be present for the route to be authorized.

Minimal form

#deadbolt:subjectPresent

Full form

#deadbolt:subjectPresent:content:[some value]:handler[the name of a handler]

Required parameters

None

Optional parameters

content
handler

Subject not present

Require no subject be present for the route to be authorized.

Minimal form

#deadbolt:subjectNotPresent

Full form

#deadbolt:subjectNotPresent:content:[some value]:handler[the name of a handler]

Required parameters

None

Optional parameters

content
handler

Dynamic

A completely user-defined constraint that uses DynamicResourceHandler#isAllowed to determine access.

Minimal form

#deadbolt:dynamic:name[constraint name]

Full form

#deadbolt:dynamic:name[constraint name]:meta[some meta data]:content:[some value]:handler[the name of a handler]

Required parameters

name - the name of the constraint

Optional parameters

meta - some meta data that will be passed to DynamicResourceHandler#isAllowed
content
handler

Pattern

This uses the Subject's Permissions to perform a variety of checks.

Minimal form

#deadbolt:pattern:value[the value to compare against a subject's permissions]:type[the match type]

Full form

#deadbolt:pattern:value[the value to compare against a subject's permissions]:type[the match type]:meta[some meta data]:invert[invert the meaning of the constraint]:content:[some value]:handler[the name of a handler]

Required parameters

name - the value to compare against a subject's permissions
type - the type of matching to use. This must be EQUALITY, REGEX or CUSTOM.

Optional parameters

meta - some meta data that will be passed to DynamicResourceHandler#checkPermission if the match type is CUSTOM
invert - invert the meaning of the constraint, i.e. a matching permission results in authorization failing. Defaults to false
content
handler

Composite

Use a hand-built composite constraint to determine access.

Minimal form

#deadbolt:composite:name[the name of the composite constraint]

Full form

#deadbolt:composite:name[the name of the composite constraint]:content:[some value]:handler[the name of a handler]

Required parameters

name - the name of the composite constraint, used to obtain the constraint from the CompositeCache

Optional parameters

content
handler

Restrict

Restrict access to only subjects with a given role. Restrict is a tricky one, because the possible combinations of roles that can be specified using the annotation form of the constraint leads to a nightmare to parse. Instead, define your role constraints within the composite cache and use the named constraint instead. deadbolt:restrict is actually a synonym for deadbolt:composite.

Minimal form

#deadbolt:restrict:name[the role name]

Full form

#deadbolt:restrict:name[the role name]:content:[some value]:handler[the name of a handler]

Required parameters

name - the name of the role

Optional parameters

content
handler

Role-based permissions

Use the permissions obtained from DeadboltHandler#getPermissionsForRole to determine access. Subjects must have at least one permission that matches at least one of the required permissions.

Minimal form

#deadbolt:rbp:name[the role name]

Full form

#deadbolt:rbp:name[the role name]:content:[some value]:handler[the name of a handler]

Required parameters

name - the name of the role, which will be passed to DeadboltHandler#getPermissionsForRole to get the required permissions

Optional parameters

content
handler