madmatah / deadbolt-2

An authorization module for the Play! framework

Deadbolt 2 – An authorisation system for Play 2

Deadbolt is an authorisation mechanism for defining access rights to certain controller methods or parts of a view using a simple AND/OR/NOT syntax.

Note that Deadbolt doesn’t provide authentication! You can use the existing authentication features of Play 2, or third-party modules such as SecureSocial alongside Deadbolt to provide authentication, and in cases where authentication is handled outside your app you can just hook up the authorisation mechanism to whatever auth system is used.

Configuration

Implement DeadboltHandler. Update your application.conf to have
deadbolt.handler=fully-qualified name of your implementation

Deadbolt doesn’t cache the role holder within the same request by default. You can enable this (typically with performance benefits) by add this to application.conf
deadbolt.cache-user=true

Installing Deadbolt

At the moment, there is no open repository for Play 2 modules, so you need to deploy it to your own repository. From the Play console,
use “publish-local” to publish to your local repository, or update Deadbolt’s Build.scala and publish to a remote repository. You will
need to update the Build.scala of your application to add a repository resolver for this. See the sample application’s Build.scala for
an example.

The dependency declaration is
“be.objectify” % “deadbolt-2_2.9.1” % “1.0”

Controller restrictions

NB Method-level annotations override controller-level annotations. All controller restrictions can be applied at the
controller level or method level.

Name Dynamic
Used for arbitrary security. Requires an implementation of a DynamicResourceHandler, accessible through the DeadboltHandler
Parameters

• value – the resource name
• meta – additional info passed into the DynamicResourceHandler at runtime
• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• @Dynamic(“foo”, “hurdy:gurdy”)
• @Dynamic(name=“foo”, meta=“hurdy:gurdy”, content=“json”, handler=my.special.FunkyDeadboltHandler)

Name Restrict
Used for static security. Requires an implementation of a RoleHolder, accessible through the DeadboltHandler. Role names are ANDed together.
Parameters

• value – the ANDed role names
• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• @Restrict(“foo”) // restricts access to RoleHolders with the foo role
• @Restrict({"foo", "bar"}) // restricts access to RoleHolders with both the foo and bar roles

Name Restrictions
Used for static security. Requires an implementation of a RoleHolder, accessible through the DeadboltHandler. Role names are ANDed together within And annotations, and ORed together between And annotations.
Parameters

• value – the restriction combinations
• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• Restrictions({And(“foo”), @And(“bar”)}) // restricts access to RoleHolders with either the foo or bar roles

Name Unrestricted
Used for Marks the resource as unrestricted – no role checking, or presence of a role holder, is required
Parameters

• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• @Unrestricted

Name RoleHolderPresent
Used for Marks the resource as restricted, but only to logged-in users
Parameters

• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• @RoleHolderPresent

Name DeadboltPattern
Used for Evaluating regular expressions or inference trees against user permissions
Parameters

• value – the pattern
• patternType – indicates the type of pattern, either REGEX or TREE. REGEX is the default value.
• content – indicates the response format in case of access failure
• handler – a specific DeadboltHandler to use for this restriction, which overrides the application-standard handler

Examples

• @DeadboltPattern(“(.)*\\.edit”)
• @DeadboltPattern(“printers.*.edit”, patternType=PatternType.TREE)

Notes:

• Regular expressions are cached for efficiency
• TREE isn’t implemented yet, this is still under development

View restrictions

If you don’t want to use the full namespace of the tags, you can import some or all of them in your template.

@import be.objectify.deadbolt.views.html._

Name restrict
Used for static security. This is the view equivalent of @Restrictions.
Parameters

• roles – a List of String arrays. Roles within an array are ANDed together; Each array represents an OR.

Examples

• @restrict(la(as(“foo”))) {
  foo
  }

Notes:
As a convenience to create the lists and arrays, you can import the methods of TemplateUtils and use the following methods
– la – create a list of arrays
– as – create an array of strings
You can see this used in the example above. A more detailed example is
@deadbolt.restrict(la(as(“foo”),as(“bar”))) {
foo
}
You can import these methods into your templates with @import be.objectify.deadbolt.utils.TemplateUtils._

Name dynamic
Used for arbitrary security. This is the view equivalent of @Dynamic
Parameters

• name – the resource name
• meta – additional info passed into the DynamicResourceHandler at runtime

Examples

• @dynamic(“foo”) {
  foo
  }
• @dynamic(“bar”, “hurdy:gurdy”) {
  bar
  }

Name roleHolderPresent
Used for ensuring the viewer is logged in. This is the view equivalent of @RoleHolderPresent
Parameters

• name – the resource name
• meta – additional info passed into the DynamicResourceHandler at runtime

Examples

• @roleHolderPresent() {
  foo
  }

Name deadboltPattern
Used for checking regexs or inference trees against user permissions. This is the view equivalent of @DeadboltPattern
Parameters

• value – the pattern value
• patternType – the pattern type, i.e. REGEX or TREE

Examples

• @deadboltPattern(“(.)*\\.edit”) {
  foo
  }

Note There is no tag equivalent of @Unrestricted