0
# Apache Shiro Spring Boot Web Starter
1

2
Apache Shiro Spring Boot Web Starter provides seamless auto-configuration integration for Apache Shiro security framework in Spring Boot web applications. This starter extends the base shiro-spring-boot-starter by adding web-specific dependencies and configurations, enabling authentication, authorization, cryptography, and session management with minimal manual setup.
3

4
## Package Information
5

6
- **Package Name**: shiro-spring-boot-web-starter
7
- **Group ID**: org.apache.shiro
8
- **Language**: Java
9
- **Package Type**: Maven Spring Boot Starter
10
- **Installation**: Add dependency to pom.xml or build.gradle
11

12
## Maven Dependency
13

14
```xml
15
<dependency>
16
    <groupId>org.apache.shiro</groupId>
17
    <artifactId>shiro-spring-boot-web-starter</artifactId>
18
    <version>2.0.5</version>
19
</dependency>
20
```
21

22
## Gradle Dependency
23

24
```groovy
25
implementation 'org.apache.shiro:shiro-spring-boot-web-starter:2.0.5'
26
```
27

28
## Core Imports
29

30
```java
31
// Basic Spring Boot application setup
32
import org.springframework.boot.SpringApplication;
33
import org.springframework.boot.autoconfigure.SpringBootApplication;
34

35
// For custom realm configuration
36
import org.apache.shiro.realm.Realm;
37
import org.springframework.context.annotation.Bean;
38
import org.springframework.context.annotation.Configuration;
39

40
// For filter chain configuration
41
import org.apache.shiro.spring.web.config.DefaultShiroFilterChainDefinition;
42
import org.apache.shiro.spring.web.config.ShiroFilterChainDefinition;
43

44
// For security annotations
45
import org.apache.shiro.authz.annotation.RequiresAuthentication;
46
import org.apache.shiro.authz.annotation.RequiresRoles;
47
import org.apache.shiro.authz.annotation.RequiresPermissions;
48

49
// For environment processing (internal use)
50
import org.springframework.boot.env.EnvironmentPostProcessor;
51
import org.springframework.core.env.ConfigurableEnvironment;
52
```
53

54
## Basic Usage
55

56
```java
57
import org.springframework.boot.SpringApplication;
58
import org.springframework.boot.autoconfigure.SpringBootApplication;
59

60
@SpringBootApplication
61
public class MyWebApplication {
62
    public static void main(String[] args) {
63
        SpringApplication.run(MyWebApplication.class, args);
64
    }
65
    
66
    // Shiro auto-configuration will automatically configure security components
67
    // No additional configuration required for basic setup
68
}
69
```
70

71
### Configuration with Custom Realm
72

73
```java
74
import org.apache.shiro.realm.Realm;
75
import org.apache.shiro.spring.web.config.DefaultShiroFilterChainDefinition;
76
import org.apache.shiro.spring.web.config.ShiroFilterChainDefinition;
77
import org.springframework.context.annotation.Bean;
78
import org.springframework.context.annotation.Configuration;
79

80
@Configuration
81
public class ShiroConfig {
82
    
83
    @Bean
84
    public Realm myRealm() {
85
        // Custom realm implementation
86
        return new MyCustomRealm();
87
    }
88
    
89
    @Bean
90
    public ShiroFilterChainDefinition shiroFilterChainDefinition() {
91
        DefaultShiroFilterChainDefinition chainDefinition = 
92
            new DefaultShiroFilterChainDefinition();
93
        
94
        chainDefinition.addPathDefinition("/login", "anon");
95
        chainDefinition.addPathDefinition("/admin/**", "authc, roles[admin]");
96
        chainDefinition.addPathDefinition("/**", "authc");
97
        
98
        return chainDefinition;
99
    }
100
}
101
```
102

103
## Configuration Properties
104

105
Configure Shiro through application.properties or application.yml:
106

107
```properties
108
# Core Shiro configuration
109
shiro.enabled=true
110
shiro.web.enabled=true
111
shiro.annotations.enabled=true
112

113
# URL configuration
114
shiro.loginUrl=/login.jsp
115
shiro.successUrl=/
116
shiro.unauthorizedUrl=/unauthorized
117

118
# Session management
119
shiro.sessionManager.sessionIdCookieEnabled=true
120
shiro.sessionManager.sessionIdUrlRewritingEnabled=false
121
shiro.sessionManager.deleteInvalidSessions=true
122
shiro.userNativeSessionManager=false
123

124
# Session cookie configuration
125
shiro.sessionManager.cookie.name=JSESSIONID
126
shiro.sessionManager.cookie.maxAge=-1
127
shiro.sessionManager.cookie.domain=
128
shiro.sessionManager.cookie.path=
129
shiro.sessionManager.cookie.secure=false
130
shiro.sessionManager.cookie.sameSite=LAX
131

132
# Remember me cookie configuration
133
shiro.rememberMeManager.cookie.name=rememberMe
134
shiro.rememberMeManager.cookie.maxAge=31536000
135
shiro.rememberMeManager.cookie.domain=
136
shiro.rememberMeManager.cookie.path=
137
shiro.rememberMeManager.cookie.secure=false
138
shiro.rememberMeManager.cookie.sameSite=LAX
139
```
140

141
## Capabilities
142

143
### Auto-Configuration Beans
144

145
The starter automatically configures essential Shiro components as Spring beans when they are not already defined.
146

147
```java { .api }
148
// Core security components
149
@Bean AuthenticationStrategy authenticationStrategy()
150
@Bean Authenticator authenticator()
151
@Bean Authorizer authorizer()
152
@Bean SessionsSecurityManager securityManager(List<Realm> realms)
153

154
// Subject and session management
155
@Bean SubjectDAO subjectDAO()
156
@Bean SessionStorageEvaluator sessionStorageEvaluator()
157
@Bean SubjectFactory subjectFactory()
158
@Bean SessionFactory sessionFactory()
159
@Bean SessionDAO sessionDAO()
160
@Bean SessionManager sessionManager()
161

162
// Web-specific components
163
@Bean Cookie sessionCookieTemplate()
164
@Bean RememberMeManager rememberMeManager()
165
@Bean Cookie rememberMeCookieTemplate()
166
@Bean ShiroFilterChainDefinition shiroFilterChainDefinition()
167
@Bean ShiroUrlPathHelper shiroUrlPathHelper()
168

169
// Filter configuration
170
@Bean ShiroFilterFactoryBean shiroFilterFactoryBean()
171
@Bean FilterRegistrationBean<AbstractShiroFilter> filterShiroFilterRegistrationBean()
172
@Bean List<String> globalFilters()
173

174
// Bean lifecycle management
175
@Bean LifecycleBeanPostProcessor lifecycleBeanPostProcessor()
176
@Bean EventBus eventBus()
177
@Bean ShiroEventBusBeanPostProcessor shiroEventBusAwareBeanPostProcessor()
178

179
// Annotation processing
180
@Bean DefaultAdvisorAutoProxyCreator defaultAdvisorAutoProxyCreator()
181
@Bean AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor(SecurityManager securityManager)
182

183
// Spring MVC integration (when RequestMappingHandlerMapping is available)
184
// Imports ShiroRequestMappingConfig for Spring MVC integration
185

186
// Environment processing
187
// ShiroEnvironmentPostProcessor automatically configures ant path matcher strategy
188
```
189

190
### Realm Auto-Discovery
191

192
Automatically configures realms from common locations:
193

194
```java { .api }
195
// Conditional realm beans - configured if resource exists
196
@Bean Realm iniClasspathRealm()  // when classpath:shiro.ini exists
197
@Bean Realm iniMetaInfClasspathRealm()  // when classpath:META-INF/shiro.ini exists
198

199
// Exception handling
200
@Bean Realm missingRealm()  // throws NoRealmBeanConfiguredException if no realm configured
201
```
202

203
### Configuration Properties API
204

205
Properties available for Spring Boot configuration:
206

207
```java { .api }
208
// Core enable/disable flags
209
Boolean shiro.enabled = true;  // Global enable/disable flag
210
Boolean shiro.web.enabled = true;  // Web-specific features
211
Boolean shiro.annotations.enabled = true;  // Annotation processing
212

213
// URL configuration
214
String shiro.loginUrl = "/login.jsp";  // Login page URL
215
String shiro.successUrl = "/";  // Post-login success URL
216
String shiro.unauthorizedUrl = null;  // Unauthorized access URL
217

218
// Session management
219
Boolean shiro.sessionManager.sessionIdCookieEnabled = true;  // Session cookies enabled
220
Boolean shiro.sessionManager.sessionIdUrlRewritingEnabled = false;  // URL rewriting for session tracking
221
Boolean shiro.sessionManager.deleteInvalidSessions = true;  // Delete invalid sessions
222
Boolean shiro.userNativeSessionManager = false;  // Use native session manager vs servlet container
223

224
// Session cookie configuration
225
String shiro.sessionManager.cookie.name = "JSESSIONID";  // Session cookie name
226
Integer shiro.sessionManager.cookie.maxAge = -1;  // Session cookie max age (default: session)
227
String shiro.sessionManager.cookie.domain = null;  // Session cookie domain
228
String shiro.sessionManager.cookie.path = null;  // Session cookie path
229
Boolean shiro.sessionManager.cookie.secure = false;  // Session cookie secure flag
230
String shiro.sessionManager.cookie.sameSite = "LAX";  // Session cookie SameSite policy
231

232
// Remember me cookie configuration
233
String shiro.rememberMeManager.cookie.name = "rememberMe";  // Remember me cookie name
234
Integer shiro.rememberMeManager.cookie.maxAge = 31536000;  // Remember me max age (1 year)
235
String shiro.rememberMeManager.cookie.domain = null;  // Remember me cookie domain
236
String shiro.rememberMeManager.cookie.path = null;  // Remember me cookie path
237
Boolean shiro.rememberMeManager.cookie.secure = false;  // Remember me cookie secure flag
238
String shiro.rememberMeManager.cookie.sameSite = "LAX";  // Remember me cookie SameSite policy
239
```
240

241
### Filter Constants
242

243
Constants for filter registration and naming:
244

245
```java { .api }
246
// ShiroWebFilterConfiguration constants
247
String REGISTRATION_BEAN_NAME = "filterShiroFilterRegistrationBean";
248
String FILTER_NAME = "shiroFilter";
249
```
250

251
### Exception Types
252

253
Exception classes that may be thrown during configuration:
254

255
```java { .api }
256
// Thrown when no realm is configured
257
class NoRealmBeanConfiguredException extends RuntimeException {
258
    // Constructor and methods inherited from RuntimeException
259
}
260
```
261

262
## Types
263

264
```java { .api }
265
// Core Shiro interfaces and classes available through auto-configuration
266
interface Realm {
267
    // Authentication and authorization interface
268
}
269

270
interface AuthenticationStrategy {
271
    // Strategy for handling multiple realms
272
}
273

274
interface Authenticator {
275
    // Authentication processing interface
276
}
277

278
interface Authorizer {
279
    // Authorization processing interface
280
}
281

282
interface SessionManager {
283
    // Session lifecycle management
284
}
285

286
interface SessionDAO {
287
    // Session persistence interface
288
}
289

290
interface SubjectDAO {
291
    // Subject state persistence interface
292
}
293

294
interface SubjectFactory {
295
    // Subject instance creation interface
296
}
297

298
interface SessionFactory {
299
    // Session instance creation interface
300
}
301

302
interface SessionStorageEvaluator {
303
    // Session storage decision interface
304
}
305

306
interface RememberMeManager {
307
    // Remember me functionality interface
308
}
309

310
class Cookie {
311
    // Cookie configuration for sessions and remember me
312
}
313

314
interface ShiroFilterChainDefinition {
315
    // Filter chain URL pattern definitions
316
}
317

318
class ShiroUrlPathHelper {
319
    // URL path resolution utility
320
}
321

322
class ShiroFilterFactoryBean {
323
    // Factory for creating Shiro filter instances
324
}
325

326
class FilterRegistrationBean<T> {
327
    // Spring Boot filter registration
328
}
329

330
class LifecycleBeanPostProcessor {
331
    // Bean lifecycle management
332
}
333

334
class EventBus {
335
    // Event handling system
336
}
337

338
class ShiroEventBusBeanPostProcessor {
339
    // Event bus integration
340
}
341

342
class DefaultAdvisorAutoProxyCreator {
343
    // AOP proxy creation for annotations
344
}
345

346
class AuthorizationAttributeSourceAdvisor {
347
    // Security annotation processing
348
}
349

350
class ShiroEnvironmentPostProcessor implements EnvironmentPostProcessor {
351
    // Automatically configures Spring MVC path matching strategy to ant_path_matcher
352
    void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application);
353
}
354
```
355

356
## Usage Examples
357

358
### Basic Web Application Setup
359

360
```java
361
import org.springframework.boot.SpringApplication;
362
import org.springframework.boot.autoconfigure.SpringBootApplication;
363

364
@SpringBootApplication
365
public class SecureWebApp {
366
    public static void main(String[] args) {
367
        SpringApplication.run(SecureWebApp.class, args);
368
    }
369
}
370

371
// application.properties
372
// shiro.loginUrl=/login
373
// shiro.successUrl=/dashboard
374
// shiro.unauthorizedUrl=/unauthorized
375
```
376

377
### Custom Realm Configuration
378

379
```java
380
import org.apache.shiro.authc.AuthenticationInfo;
381
import org.apache.shiro.authc.AuthenticationToken;
382
import org.apache.shiro.authc.SimpleAuthenticationInfo;
383
import org.apache.shiro.authz.AuthorizationInfo;
384
import org.apache.shiro.authz.SimpleAuthorizationInfo;
385
import org.apache.shiro.realm.AuthorizingRealm;
386
import org.apache.shiro.subject.PrincipalCollection;
387
import org.springframework.stereotype.Component;
388

389
@Component
390
public class DatabaseRealm extends AuthorizingRealm {
391
    
392
    @Override
393
    protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {
394
        // Authorization logic
395
        return new SimpleAuthorizationInfo();
396
    }
397
    
398
    @Override
399
    protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) {
400
        // Authentication logic
401
        return new SimpleAuthenticationInfo();
402
    }
403
}
404
```
405

406
### Security Filter Chain Configuration
407

408
```java
409
import org.apache.shiro.spring.web.config.DefaultShiroFilterChainDefinition;
410
import org.apache.shiro.spring.web.config.ShiroFilterChainDefinition;
411
import org.springframework.context.annotation.Bean;
412
import org.springframework.context.annotation.Configuration;
413

414
@Configuration
415
public class ShiroWebConfig {
416
    
417
    @Bean
418
    public ShiroFilterChainDefinition shiroFilterChainDefinition() {
419
        DefaultShiroFilterChainDefinition definition = 
420
            new DefaultShiroFilterChainDefinition();
421
        
422
        // Public endpoints
423
        definition.addPathDefinition("/", "anon");
424
        definition.addPathDefinition("/login", "anon");
425
        definition.addPathDefinition("/css/**", "anon");
426
        definition.addPathDefinition("/js/**", "anon");
427
        
428
        // Protected endpoints
429
        definition.addPathDefinition("/admin/**", "authc, roles[admin]");
430
        definition.addPathDefinition("/user/**", "authc");
431
        definition.addPathDefinition("/**", "authc");
432
        
433
        return definition;
434
    }
435
}
436
```
437

438
### Using Security Annotations
439

440
```java
441
import org.apache.shiro.authz.annotation.RequiresAuthentication;
442
import org.apache.shiro.authz.annotation.RequiresPermissions;
443
import org.apache.shiro.authz.annotation.RequiresRoles;
444
import org.springframework.web.bind.annotation.GetMapping;
445
import org.springframework.web.bind.annotation.PostMapping;
446
import org.springframework.web.bind.annotation.RequestBody;
447
import org.springframework.web.bind.annotation.RestController;
448
import java.util.List;
449

450
@RestController
451
public class SecureController {
452
    
453
    @RequiresAuthentication
454
    @GetMapping("/profile")
455
    public String getProfile() {
456
        return "User profile";
457
    }
458
    
459
    @RequiresRoles("admin")
460
    @GetMapping("/admin/users")
461
    public List<User> getUsers() {
462
        return userService.getAllUsers();
463
    }
464
    
465
    @RequiresPermissions("user:create")
466
    @PostMapping("/users")
467
    public User createUser(@RequestBody User user) {
468
        return userService.createUser(user);
469
    }
470
}
471
```
472

473
### Cookie Configuration Example
474

475
```java
476
import org.springframework.context.annotation.Configuration;
477
import org.springframework.boot.context.properties.ConfigurationProperties;
478

479
@Configuration
480
public class ShiroSecurityConfig {
481
    
482
    // Configure secure cookies for production
483
    // application.properties:
484
    /*
485
    shiro.sessionManager.cookie.secure=true
486
    shiro.sessionManager.cookie.sameSite=STRICT
487
    shiro.rememberMeManager.cookie.secure=true
488
    shiro.rememberMeManager.cookie.sameSite=STRICT
489
    shiro.rememberMeManager.cookie.maxAge=604800
490
    */
491
}
492
```
493

494
### Environment-Specific Configuration
495

496
```properties
497
# Development environment (application-dev.properties)
498
shiro.sessionManager.cookie.secure=false
499
shiro.sessionManager.cookie.sameSite=LAX
500
shiro.rememberMeManager.cookie.secure=false
501

502
# Production environment (application-prod.properties)
503
shiro.sessionManager.cookie.secure=true
504
shiro.sessionManager.cookie.sameSite=STRICT
505
shiro.rememberMeManager.cookie.secure=true
506
shiro.sessionManager.cookie.domain=.yourdomain.com
507
```
508

509
## Notes
510

511
- This starter is a dependency aggregation module that pulls in the base `shiro-spring-boot-starter` and adds web-specific dependencies
512
- All auto-configured beans are conditional and can be overridden by defining custom beans
513
- The starter integrates seamlessly with Spring Boot's auto-configuration system
514
- Supports both programmatic configuration and properties-based configuration
515
- Automatically registers the Shiro filter in the Spring Boot servlet container
516
- Enables Shiro security annotations through AOP integration
517
- Compatible with Spring Boot 2.x and 3.x (check compatibility matrix for specific versions)