Apache Shiro support for the Jersey JAX-RS implementation.
Shiro 1.4 is in the
works and includes a new JAX-RS module based on shiro-jersey
.
See:
Add the following dependencies to pom.xml
in an existing project already using Jersey:
<dependency>
<groupId>org.secnod.shiro</groupId>
<artifactId>shiro-jersey</artifactId>
<version>0.2.0</version>
</dependency>
Version compatibility:
Jersey | Shiro Jersey |
---|---|
2.0-2.25 | 0.2.0 |
1.x | 0.1.1 |
If you are upgrading from Jersey 1.x, see the upgrade instructions.
An example web application is provided complete with source code and web content.
The rest of this section describes how Shiro has been added to the example application.
Add the Shiro servlet filter in web.xml
:
<context-param>
<param-name>shiroConfigLocations</param-name>
<param-value>classpath:shiro.ini</param-value>
</context-param>
<listener>
<listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
</listener>
<filter>
<filter-name>ShiroFilter</filter-name>
<filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>ShiroFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>ERROR</dispatcher>
</filter-mapping>
Then register the following components in the JAX-RS application:
public class ApiApplication extends ResourceConfig {
public ApiApplication() {
register(new AuthorizationFilterFeature());
register(new SubjectFactory());
register(new AuthInjectionBinder());
}
}
Finally configure shiro.ini
in the default package on the classpath:
[main]
[users]
exampleuser = examplepassword, examplerole
[roles]
examplerole = something:readpermission
[urls]
/** = noSessionCreation, authcBasic
Real applications should of course not store users and passwords in the INI-file. See the Shiro configuration documentation.
This section describes the different alternatives for how Shiro can be used from JAX-RS.
JAX-RS resource classes and methods can be annotated with the standard Shiro annotations.
The authorization requirements can for example be declared with @RequiresPermissions
on JAX-RS resource classes /
methods:
@Path("/auth")
@Produces(MediaType.TEXT_PLAIN)
@RequiresPermissions("protected:read")
public class AuthResource {
@GET
public String get() {
return "OK";
}
@PUT
@RequiresPermissions("protected:write")
public String set(String value) {
return value;
}
}
The example above can be summarized as:
protected:read
protected:read
and protected:write
Programmatic authorization is done by injecting the Shiro Subject as a method parameter:
@Path("/auth")
@Produces(MediaType.TEXT_PLAIN)
public class AuthResource {
@GET
public String get(@Auth Subject subject) {
subject.checkPermission("protected:read");
return "OK";
}
}
Injecting the Subject is just a convenience over calling [SecurityUtils.getSubject()](http://shiro.apache.org/static/1.2.2/apidocs/org/apache/shiro/SecurityUtils.html#getSubject()).
Declarative and programmatic authorization are often combined when some permissions are static and some are dynamic:
@Path("/auth")
@Produces(MediaType.TEXT_PLAIN)
public class AuthResource {
@GET
@RequiresPermissions("static-permission")
public String get(@Auth Subject subject) {
subject.checkPermission(dynamicPermission());
return "OK";
}
}
Instead of using the Shiro Subject
class directly one can use an application specific user class for programmatic
authorization:
@Path("/auth")
@Produces(MediaType.TEXT_PLAIN)
public class AuthResource {
@GET
public String get(@Auth User user) {
user.checkBusinessRulePermission();
return "OK";
}
}
A custom User
class is a convenient way of implementing application
specific authorization based on business rules on the user's data.
More authorization as rules means less authorization as permissions and hence fewer permissions to maintain.
See:
@Auth
annotation.These instructions assume that the JAX-RS application is a subclass of
org.glassfish.jersey.server.ResourceConfig
.
Note that JAX-RS component registration is done by ResourceConfig.register()
instead of javax.ws.rs.core.Application.getSingletons()
.
AuthorizationFilterFeature
replaces ShiroResourceFilterFactory
Remove the configuration of ShiroResourceFilterFactory
from web.xml
and
register AuthorizationFilterFeature
as a JAX-RS component.
SubjectFactory
replaces SubjectInjectableProvider
TypeFactory
replaces AuthInjectableProvider
The integration tests for this project can be run as follows:
mvn -Pintegration-tests test