0
# Apache Shiro Core
1

2
Apache Shiro Core is the foundational module of the Apache Shiro security framework, providing essential security services for Java applications. It implements a comprehensive authentication and authorization system with support for multiple realms, role-based and permission-based access control, and pluggable authentication mechanisms.
3

4
## Package Information
5

6
- **Package Name**: org.apache.shiro:shiro-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.shiro</groupId>
13
    <artifactId>shiro-core</artifactId>
14
    <version>2.0.5</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.shiro.SecurityUtils;
22
import org.apache.shiro.subject.Subject;
23
import org.apache.shiro.mgt.SecurityManager;
24
```
25

26
For authentication:
27
```java
28
import org.apache.shiro.authc.UsernamePasswordToken;
29
import org.apache.shiro.authc.AuthenticationException;
30
```
31

32
For authorization:
33
```java
34
import org.apache.shiro.authz.Permission;
35
import org.apache.shiro.authz.permission.WildcardPermission;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.apache.shiro.SecurityUtils;
42
import org.apache.shiro.subject.Subject;
43
import org.apache.shiro.authc.UsernamePasswordToken;
44
import org.apache.shiro.authc.AuthenticationException;
45

46
// Get the current user (Subject)
47
Subject currentUser = SecurityUtils.getSubject();
48

49
// Authenticate the user
50
if (!currentUser.isAuthenticated()) {
51
    UsernamePasswordToken token = new UsernamePasswordToken("username", "password");
52
    try {
53
        currentUser.login(token);
54
        System.out.println("User authenticated successfully");
55
    } catch (AuthenticationException e) {
56
        System.out.println("Authentication failed: " + e.getMessage());
57
    }
58
}
59

60
// Check authorization
61
if (currentUser.hasRole("admin")) {
62
    System.out.println("User has admin role");
63
}
64

65
if (currentUser.isPermitted("user:create")) {
66
    System.out.println("User can create users");
67
}
68

69
// Logout
70
currentUser.logout();
71
```
72

73
## Architecture
74

75
Apache Shiro Core is built around several key components working together:
76

77
- **Subject**: The current user/security context - primary interface for all security operations
78
- **SecurityManager**: The central security coordinator managing authentication, authorization, and sessions
79
- **Realms**: Data source abstractions that connect to your security data (databases, LDAP, files, etc.)
80
- **Authentication**: Identity verification with support for multiple authentication mechanisms
81
- **Authorization**: Permission and role-based access control with fine-grained permissions
82
- **Sessions**: Security-aware session management independent of web containers
83
- **Cryptography**: Password hashing, encryption, and secure random number generation
84

85
This design provides a clean separation of concerns while maintaining flexibility for different deployment scenarios, from standalone applications to enterprise web applications.
86

87
## Capabilities
88

89
### Core Subject Operations
90

91
Primary interface for interacting with the current user's security context. The Subject represents the security-specific user view and provides all essential security operations.
92

93
```java { .api }
94
public interface Subject {
95
    // Authentication operations
96
    void login(AuthenticationToken token) throws AuthenticationException;
97
    boolean isAuthenticated();
98
    boolean isRemembered();
99
    void logout();
100
    
101
    // Principal access
102
    Object getPrincipal();
103
    PrincipalCollection getPrincipals();
104
    
105
    // Permission checking
106
    boolean isPermitted(String permission);
107
    boolean isPermitted(Permission permission);
108
    boolean[] isPermitted(String... permissions);
109
    boolean[] isPermitted(List<Permission> permissions);
110
    boolean isPermittedAll(String... permissions);
111
    boolean isPermittedAll(Collection<Permission> permissions);
112
    void checkPermission(String permission) throws AuthorizationException;
113
    void checkPermission(Permission permission) throws AuthorizationException;
114
    void checkPermissions(String... permissions) throws AuthorizationException;
115
    void checkPermissions(Collection<Permission> permissions) throws AuthorizationException;
116
    
117
    // Role checking
118
    boolean hasRole(String roleIdentifier);
119
    boolean[] hasRoles(List<String> roleIdentifiers);
120
    boolean hasAllRoles(Collection<String> roleIdentifiers);
121
    void checkRole(String roleIdentifier) throws AuthorizationException;
122
    void checkRoles(Collection<String> roleIdentifiers) throws AuthorizationException;
123
    void checkRoles(String... roleIdentifiers) throws AuthorizationException;
124
    
125
    // Session operations
126
    Session getSession();
127
    Session getSession(boolean create);
128
    
129
    // Execution context operations
130
    <V> V execute(Callable<V> callable) throws ExecutionException;
131
    void execute(Runnable runnable);
132
    <V> Callable<V> associateWith(Callable<V> callable);
133
    Runnable associateWith(Runnable runnable);
134
    
135
    // RunAs operations
136
    boolean isRunAs();
137
    PrincipalCollection getPreviousPrincipals();
138
    PrincipalCollection releaseRunAs();
139
}
140
```
141

142
[Subject Operations](./subject-operations.md)
143

144
### Types
145

146
```java { .api }
147
public interface PrincipalCollection extends Iterable, Serializable {
148
    Object getPrimaryPrincipal();
149
    List asList();
150
    Set asSet();
151
    Collection fromRealm(String realmName);
152
    Set<String> getRealmNames();
153
    boolean isEmpty();
154
}
155
```
156

157
### Security Manager
158

159
Central coordinator for all security operations, managing the interaction between subjects, realms, sessions, and caches. The SecurityManager is the heart of Shiro's architecture.
160

161
```java { .api }
162
public interface SecurityManager extends Authenticator, Authorizer, SessionManager {
163
    Subject createSubject(SubjectContext context);
164
    Subject login(Subject subject, AuthenticationToken authenticationToken) throws AuthenticationException;
165
    void logout(Subject subject);
166
}
167

168
public class DefaultSecurityManager implements SecurityManager {
169
    public DefaultSecurityManager();
170
    public DefaultSecurityManager(Realm singleRealm);
171
    public DefaultSecurityManager(Collection<Realm> realms);
172
    public void setRealms(Collection<Realm> realms);
173
    public void setAuthenticator(Authenticator authenticator);
174
    public void setAuthorizer(Authorizer authorizer);
175
}
176
```
177

178
[Security Manager](./security-manager.md)
179

180
### Authentication Framework
181

182
Comprehensive authentication system supporting multiple authentication mechanisms, credential matching, and multi-realm authentication strategies.
183

184
```java { .api }
185
public interface AuthenticationToken {
186
    Object getPrincipal();
187
    Object getCredentials();
188
}
189

190
public interface RememberMeAuthenticationToken extends AuthenticationToken {
191
    boolean isRememberMe();
192
}
193

194
public interface HostAuthenticationToken extends AuthenticationToken {
195
    String getHost();
196
}
197

198
public class UsernamePasswordToken implements AuthenticationToken, 
199
        RememberMeAuthenticationToken, HostAuthenticationToken {
200
    public UsernamePasswordToken();
201
    public UsernamePasswordToken(String username, char[] password);
202
    public UsernamePasswordToken(String username, String password);
203
    public UsernamePasswordToken(String username, char[] password, String host);
204
    public UsernamePasswordToken(String username, String password, String host);
205
    public UsernamePasswordToken(String username, char[] password, boolean rememberMe);
206
    public UsernamePasswordToken(String username, String password, boolean rememberMe);
207
    public UsernamePasswordToken(String username, char[] password, boolean rememberMe, String host);
208
    public UsernamePasswordToken(String username, String password, boolean rememberMe, String host);
209
    
210
    public String getUsername();
211
    public char[] getPassword();
212
    public String getHost();
213
    public boolean isRememberMe();
214
    public void setRememberMe(boolean rememberMe);
215
    public void clear();
216
}
217

218
public interface Authenticator {
219
    AuthenticationInfo authenticate(AuthenticationToken authenticationToken) 
220
        throws AuthenticationException;
221
}
222
```
223

224
[Authentication](./authentication.md)
225

226
### Authorization Framework
227

228
Role-based and permission-based access control with support for wildcard permissions, annotation-driven security, and flexible authorization policies.
229

230
```java { .api }
231
public interface Authorizer {
232
    boolean isPermitted(PrincipalCollection principals, String permission);
233
    boolean hasRole(PrincipalCollection principals, String roleIdentifier);
234
    void checkPermission(PrincipalCollection principals, String permission) 
235
        throws AuthorizationException;
236
}
237

238
public class WildcardPermission implements Permission, Serializable {
239
    public WildcardPermission(String wildcardString);
240
    public WildcardPermission(String wildcardString, boolean caseSensitive);
241
    public boolean implies(Permission p);
242
    public String toString();
243
    public boolean equals(Object o);
244
    public int hashCode();
245
}
246
```
247

248
[Authorization](./authorization.md)
249

250
### Realm Framework
251

252
Data source abstractions that connect Shiro to your security data sources like databases, LDAP directories, or configuration files. Realms handle both authentication and authorization data retrieval.
253

254
```java { .api }
255
public interface Realm {
256
    boolean supports(AuthenticationToken token);
257
    AuthenticationInfo getAuthenticationInfo(AuthenticationToken token) 
258
        throws AuthenticationException;
259
}
260

261
public abstract class AuthorizingRealm extends AuthenticatingRealm {
262
    protected abstract AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals);
263
    protected abstract AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) 
264
        throws AuthenticationException;
265
}
266
```
267

268
[Realms](./realms.md)
269

270
### Session Management
271

272
Security-aware session management that works independently of web containers, providing consistent session handling across different deployment environments.
273

274
```java { .api }
275
public interface Session {
276
    Serializable getId();
277
    Date getStartTimestamp();
278
    Date getLastAccessTime();
279
    long getTimeout() throws InvalidSessionException;
280
    void setTimeout(long maxIdleTimeInMillis) throws InvalidSessionException;
281
    String getHost();
282
    void touch() throws InvalidSessionException;
283
    void stop() throws InvalidSessionException;
284
    Collection<Object> getAttributeKeys() throws InvalidSessionException;
285
    Object getAttribute(Object key) throws InvalidSessionException;
286
    void setAttribute(Object key, Object value) throws InvalidSessionException;
287
    Object removeAttribute(Object key) throws InvalidSessionException;
288
}
289

290
public interface SessionManager {
291
    Session start(SessionContext context);
292
    Session getSession(SessionKey key);
293
}
294
```
295

296
[Session Management](./session-management.md)
297

298
### Security Annotations
299

300
Method-level security annotations for declarative authorization and authentication requirements, enabling aspect-oriented security.
301

302
```java { .api }
303
@Target({ElementType.TYPE, ElementType.METHOD})
304
@Retention(RetentionPolicy.RUNTIME)
305
@Documented
306
public @interface RequiresAuthentication {
307
}
308

309
@Target({ElementType.TYPE, ElementType.METHOD})
310
@Retention(RetentionPolicy.RUNTIME)
311
@Documented
312
public @interface RequiresRoles {
313
    String[] value();
314
    Logical logical() default Logical.AND;
315
}
316

317
@Target({ElementType.TYPE, ElementType.METHOD})
318
@Retention(RetentionPolicy.RUNTIME)
319
@Documented
320
public @interface RequiresPermissions {
321
    String[] value();
322
    Logical logical() default Logical.AND;
323
}
324
```
325

326
[Security Annotations](./security-annotations.md)
327

328
### Utilities and Configuration
329

330
Essential utilities for initialization, configuration, thread context management, and integration with various environments and frameworks.
331

332
```java { .api }
333
public abstract class SecurityUtils {
334
    public static Subject getSubject();
335
    public static SecurityManager getSecurityManager();
336
    public static void setSecurityManager(SecurityManager securityManager);
337
}
338

339
public abstract class ThreadContext {
340
    public static SecurityManager getSecurityManager();
341
    public static void bind(SecurityManager securityManager);
342
    public static SecurityManager unbindSecurityManager();
343
    public static Subject getSubject();
344
    public static void bind(Subject subject);
345
    public static Subject unbindSubject();
346
    public static void remove();
347
}
348
```
349

350
[Utilities](./utilities.md)
351

352
## Exception Hierarchy
353

354
```java { .api }
355
public class ShiroException extends RuntimeException {
356
    public ShiroException(String message);
357
    public ShiroException(Throwable cause);
358
}
359

360
public class AuthenticationException extends ShiroException {
361
    public AuthenticationException(String message);
362
}
363

364
public class AuthorizationException extends ShiroException {
365
    public AuthorizationException(String message);
366
}
367

368
public class SessionException extends ShiroException {
369
    public SessionException(String message);
370
}
371
```