| #parse("templates/includes.vtl") |
| |
| Apache Shiro JAX-RS Support |
| =========================== |
| |
| Apache Shiro's JAX-RS support is built on top of the more general [Servlet](web.html) support, and requires Shiro's Servlet Filter to be setup. The Servlet Filter can be setup by using Shiro's Servlet fragment, `web.xml` configuration, or programmatically. |
| |
| Dependencies |
| ------------ |
| |
| Include the `shiro-servlet-plugin` and `shiro-jaxrs` dependencies in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this). |
| |
| #dependencies('cli', [['org.apache.shiro', 'shiro-servlet-plugin', "${latestRelease}"],['org.apache.shiro', 'shiro-jaxrs', "${latestRelease}"]]) |
| |
| For information on other ways to set up the Apache Shiro Filter see the [web documentation](web.html). |
| |
| Configuration |
| ------------- |
| |
| There are two basic approaches used to define the authentication and authorization for your JAX-RS resources: paths defined statically in configuration, or via annotations on your resource. |
| |
| If you are using [Guice](guice.html) or [Spring](spring.html) see those docs on how to configure Shiro. |
| |
| ### Paths defined in `shiro.ini` |
| |
| Just like any other web application, your resources paths can be defined in a `shiro.ini` file. For example, to require resources under `/api/secured` to use basic authentication, your `[urls]` section would look like: |
| |
| ``` ini |
| [urls] |
| |
| /api/secured/** = authcBaic |
| ``` |
| |
| See the [web documentation](web.html) for more details. |
| |
| The other, probably more popular, option is to use Shiro's [annotations](java-annotations-list.html) along side other JAX-RS annotations on your resources. However you **MUST** still define at least one path in your `shiro.ini` file. |
| |
| The below code block will allow for basic authentication but NOT require it (via the `permissive` flag). This way all of the resources under `/api` can optional require authentication and authorization based on annotations. |
| |
| ``` ini |
| [urls] |
| |
| /api/** = authcBaic[permissive] |
| ``` |
| |
| Example |
| ------- |
| |
| To create a simple example we can define a JAX-RS resource `HelloShiro`: |
| |
| ``` java |
| @Path("/shiro") |
| public class HelloShiro { |
| |
| @GET |
| @RequiresUser |
| public String sayHelloShiro() { |
| return "Hello!"; |
| } |
| |
| @GET |
| @Path("define") |
| @RequiresPermissions("hello:define") |
| public String defineShiro() { |
| return "Shiro is the Japanese term for a castle"; |
| } |
| } |
| ``` |
| |
| This resource has two end points, the first allows access by any logged in user, the second any user with the [permission](permissions.html) `hello:define`. |
| |
| The corresponding JAX-RS Application class: |
| |
| ``` java |
| @ApplicationPath("/api") |
| public class ExampleApp extends Application { |
| |
| @Override |
| public Set<Class<?>> getClasses() { |
| Set<Class<?>> classes = new HashSet<>(); |
| |
| // register the Shiro Feature |
| classes.add(ShiroFeature.class); |
| |
| // register resources: |
| classes.add(HelloShiro.class); |
| |
| return classes; |
| } |
| } |
| ``` |
| |
| The `ShiroFeature` does three things: |
| |
| * configures exception mapping from Shiro's `AuthorizationException` to HTTP status codes (401 and 403) |
| * exposes Shiro's `Subject` as a `java.security.Principal` |
| * Configures processing of Shiro's annotations |
| |
| In the above example, requests to either `/api/shiro` or `/api/shiro/define` will return an HTTP status of `401` if a user is not currently logged in. A request to `/api/shiro/define` made by a user without the `hello:define` will return a `403`. |
| |
| Want to see more? |
| ----------------- |
| |
| You can find portable JAX-RS application that runs with [Jersey](https://jersey.java.net/), [RestEasy](http://resteasy.jboss.org/) or [Apache CXF](https://cxf.apache.org) in the [samples](https://github.com/apache/shiro/tree/master/samples) directory on Github. |
| |
| <input type="hidden" id="ghEditPage" value="jaxrs.md.vtl"></input> |