spring-boot.md.vtl

#parse("templates/includes.vtl")

<a name="Spring-IntegratingApacheShirointoSpringbasedApplications"></a>
#Integrating Apache Shiro into Spring-Boot Applications

Shiro's Spring-Boot integration is the easiest way to integrate Shiro into a Spring-base application, for more general Spring Framework integration, take a the [annotation](spring-framework.html) or [XML](spring-xml.html) guides.  

<a name="Spring-StandaloneApplications"></a>
Standalone Applications
---

Include the Shiro Spring starter dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).

#dependencies('cli', [['org.apache.shiro', 'shiro-spring-boot-starter', "${earlyRelease}"]])

The only thing that is left is to configure a [realm](realm.html):

``` java
@Bean
public Realm realm() {
  ...
}
```

The easiest way to setup Shiro, so that all SecurityUtils.* methods work in all cases, is to make the `SecurityManager` bean a static singleton.  DO NOT do this in web applications - see the [Web Applications](#Spring-WebApplications) section below instead.
 
``` java
@Autowired
private SecurityManager securityManager;
    
 @PostConstruct
 private void initStaticSecurityManager() {
     SecurityUtils.setSecurityManager(securityManager);
 }
```

That is it, now you can get the current `Subject` using:

``` java
SecurityUtils.getSubject();
```

You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/master/samples/spring-boot).

<a name="Spring-WebApplications"></a>
Web Applications
---

Shiro has first-class support for Spring web applications. In a web application, all Shiro-accessible web requests must go through a master Shiro Filter. This filter itself is extremely powerful, allowing for ad-hoc custom filter chains to be executed based on any URL path expression.

First include the Shiro Spring web starter dependency in you application classpath (we recomend using a tool such as Apache Maven or Gradle to manage this).

#dependencies('web', [['org.apache.shiro', 'shiro-spring-boot-web-starter', "${earlyRelease}"]])

Provide a Realm implementation:
``` java
@Bean
public Realm realm() {
  ...
}
```

And finally a `ShiroFilterChainDefinition` which will map any application specific paths to a given filter, in order to allow different paths different levels of access. 

``` java
@Bean
public ShiroFilterChainDefinition shiroFilterChainDefinition() {
    DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
    
    // logged in users with the 'admin' role
    chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
    
    // logged in users with the 'document:read' permission
    chainDefinition.addPathDefinition("/docs/**", "authc, perms[document:read]");
    
    // all other paths require a logged in user
    chainDefinition.addPathDefinition("/**", "authc");
    return chainDefinition;
}
```

If you are using Shiro's annotations see the [annotation](#Spring-annotations-web) section below.

You can see a full example in our [samples on Github](https://github.com/apache/shiro/tree/master/samples/spring-boot-web).

<a name="Spring-annotations"></a>
Enabling Shiro Annotations
---

In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc.) These annotations are enabled automatically in both starters listed above.

Simply annotate your methods in order to use them:

``` java
@RequiresPermissions("document:read")
public void readDocument() {
    ...
}
```

<a name="Spring-annotations-web"></a>
#[[###]]# Annotations and Web Applications

Shiro annotations are fully supported for use in `@Controller` classes, for example:

``` java
@Controller
public class AccountInfoController {

    @RequiresRoles("admin")
    @RequestMapping("/admin/config")
    public String adminConfig(Model model) {
        return "view";
    }
}
```

A `ShiroFilterChainDefinition` bean with at least one definition is still required for this to work, either configure all paths to be accessable via the `anon` filter or a filter in 'permissive' mode, for example: `authcBasic[permissive]`.

``` java
@Bean
public ShiroFilterChainDefinition shiroFilterChainDefinition() {
    DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
    chainDefinition.addPathDefinition("/**", "anon"); // all paths are managed via annotations
    
    // or allow basic authentication, but NOT require it.
    // chainDefinition.addPathDefinition("/**", "authcBasic[permissive]"); 
    return chainDefinition;
}
```

<a name="Spring-caching"></a>
# Caching 

Enabling caching is as simple as providing a [CacheManager](http://shiro.apache.org/caching.html) bean:

``` java
@Bean
protected CacheManager cacheManager() {
    return new MemoryConstrainedCacheManager();
}
```

<!-- Work around for table styling until, all pages are updated. -->
#mdStyle()

# Configuration Properties

| Key | Default Value | Description |
| --- | ------------- | ----------- |
| shiro.enabled | `true` | Enables Shiro's Spring module |
| shiro.web.enabled | `true` | Enables Shiro's Spring web module |
| shiro.annotations.enabled | `true` | Enables Spring support for Shiro's annotations |
| shiro.sessionManager.deleteInvalidSessions | `true` | Remove invalid session from session storage |
| shiro.sessionManager.sessionIdCookieEnabled | `true` | Enable session ID to cookie, for session tracking |
| shiro.sessionManager.sessionIdUrlRewritingEnabled | `true` | Enable session URL rewriting support |
| shiro.userNativeSessionManager | `false` | If enabled Shiro will manage the HTTP sessions instead of the container |
| shiro.sessionManager.cookie.name | `JSESSIONID` | Session cookie name |
| shiro.sessionManager.cookie.maxAge | `-1` | Session cookie max age |
| shiro.sessionManager.cookie.domain |  null | Session cookie domain |
| shiro.sessionManager.cookie.path | null | Session cookie path |
| shiro.sessionManager.cookie.secure |  `false` | Session cookie secure flag |
| shiro.rememberMeManager.cookie.name | `rememberMe` | RememberMe cookie name |
| shiro.rememberMeManager.cookie.maxAge |  one year | RememberMe cookie max age |
| shiro.rememberMeManager.cookie.domain | null | RememberMe cookie domain|
| shiro.rememberMeManager.cookie.path |  null | RememberMe cookie path|
| shiro.rememberMeManager.cookie.secure | `false` | RememberMe cookie secure flag|
| shiro.loginUrl | `/login.jsp` | Login URL used when unauthenticated users are redirected to login page |
| shiro.successUrl | `/` | Default landing page after a user logs in (if alternative cannot be found in the current session) |
| shiro.unauthorizedUrl | null | Page to redirect user to if they are unauthorized (403 page) |

<input type="hidden" id="ghEditPage" value="spring-boot.md.vtl"></input>