0
# Security Manager
1

2
The SecurityManager is the central coordinator for all security operations in Apache Shiro. It manages the interaction between subjects, realms, sessions, caches, and other security components. The SecurityManager is responsible for creating subjects, orchestrating authentication and authorization operations, and managing the overall security context.
3

4
## Capabilities
5

6
### Core Security Manager Interface
7

8
The primary interface defining the essential security management operations.
9

10
```java { .api }
11
/**
12
 * A SecurityManager executes all security operations for all Subjects (aka users) across a single application.
13
 */
14
public interface SecurityManager {
15
    /**
16
     * Logs in a Subject based on the submitted AuthenticationToken.
17
     * @param subject the subject to log in
18
     * @param token the authentication token submitted for the login attempt
19
     * @return updated AuthenticationInfo for the logged-in Subject
20
     * @throws AuthenticationException if the login attempt failed
21
     */
22
    Subject login(Subject subject, AuthenticationToken token) throws AuthenticationException;
23

24
    /**
25
     * Logs out the specified Subject from the system.
26
     * @param subject the subject to log out
27
     */
28
    void logout(Subject subject);
29

30
    /**
31
     * Creates a Subject instance reflecting the application's current execution state.
32
     * @param context the contextual data used by the implementation to construct an appropriate Subject
33
     * @return a Subject instance reflecting the application's current execution state
34
     */
35
    Subject createSubject(SubjectContext context);
36
}
37
```
38

39
### Default Security Manager Implementation
40

41
The primary implementation of SecurityManager that provides comprehensive security management.
42

43
```java { .api }
44
/**
45
 * The DefaultSecurityManager is a concrete implementation of the SecurityManager interface
46
 * that supports most out-of-the-box requirements for single-application security management.
47
 */
48
public class DefaultSecurityManager implements SecurityManager {
49
    /**
50
     * Default no-argument constructor.
51
     */
52
    public DefaultSecurityManager();
53

54
    /**
55
     * Creates a new DefaultSecurityManager instance with a single Realm.
56
     * @param realm the single Realm to use for authentication and authorization operations
57
     */
58
    public DefaultSecurityManager(Realm realm);
59

60
    /**
61
     * Creates a new DefaultSecurityManager instance with the specified collection of Realms.
62
     * @param realms the collection of Realms to use for authentication and authorization operations  
63
     */
64
    public DefaultSecurityManager(Collection<Realm> realms);
65

66
    /**
67
     * Sets the collection of Realms used by this SecurityManager.
68
     * @param realms the collection of Realms to use for authentication and authorization operations
69
     */
70
    public void setRealms(Collection<Realm> realms);
71

72
    /**
73
     * Returns the collection of Realms used by this SecurityManager for authentication and authorization.
74
     * @return the collection of Realms used by this SecurityManager
75
     */
76
    public Collection<Realm> getRealms();
77

78
    /**
79
     * Sets the Authenticator used during authentication attempts.
80
     * @param authenticator the Authenticator used during authentication attempts
81
     */
82
    public void setAuthenticator(Authenticator authenticator);
83

84
    /**
85
     * Returns the Authenticator used during authentication attempts.
86
     * @return the Authenticator used during authentication attempts
87
     */
88
    public Authenticator getAuthenticator();
89

90
    /**
91
     * Sets the Authorizer used during authorization operations.
92
     * @param authorizer the Authorizer used during authorization operations
93
     */
94
    public void setAuthorizer(Authorizer authorizer);
95

96
    /**
97
     * Returns the Authorizer used during authorization operations.  
98
     * @return the Authorizer used during authorization operations
99
     */
100
    public Authorizer getAuthorizer();
101

102
    /**
103
     * Sets the SessionManager used to manage Sessions for all application users.
104
     * @param sessionManager the SessionManager used to manage Sessions for all application users
105
     */
106
    public void setSessionManager(SessionManager sessionManager);
107

108
    /**
109
     * Returns the SessionManager used to manage Sessions for all application users.
110
     * @return the SessionManager used to manage Sessions for all application users
111
     */
112
    public SessionManager getSessionManager();
113

114
    /**
115
     * Sets the CacheManager used for caching authentication and authorization information.
116
     * @param cacheManager the CacheManager used for caching
117
     */
118
    public void setCacheManager(CacheManager cacheManager);
119

120
    /**
121
     * Returns the CacheManager used for caching authentication and authorization information.
122
     * @return the CacheManager used for caching
123
     */
124
    public CacheManager getCacheManager();
125

126
    /**
127
     * Sets the RememberMeManager used to manage remember-me functionality.
128
     * @param rememberMeManager the RememberMeManager used to manage remember-me functionality
129
     */
130
    public void setRememberMeManager(RememberMeManager rememberMeManager);
131

132
    /**
133
     * Returns the RememberMeManager used to manage remember-me functionality.
134
     * @return the RememberMeManager used to manage remember-me functionality
135
     */
136
    public RememberMeManager getRememberMeManager();
137
}
138
```
139

140
**Usage Example:**
141

142
```java
143
// Basic setup with single realm
144
Realm myRealm = new MyCustomRealm();
145
SecurityManager securityManager = new DefaultSecurityManager(myRealm);
146
SecurityUtils.setSecurityManager(securityManager);
147

148
// Advanced setup with multiple components
149
DefaultSecurityManager manager = new DefaultSecurityManager();
150

151
// Configure realms
152
Collection<Realm> realms = Arrays.asList(
153
    new JdbcRealm(),
154
    new LdapRealm(),
155
    new IniRealm()
156
);
157
manager.setRealms(realms);
158

159
// Configure session management
160
DefaultSessionManager sessionManager = new DefaultSessionManager();
161
sessionManager.setGlobalSessionTimeout(30 * 60 * 1000); // 30 minutes
162
manager.setSessionManager(sessionManager);
163

164
// Configure caching
165
EhCacheManager cacheManager = new EhCacheManager();
166
manager.setCacheManager(cacheManager);
167

168
// Set as application security manager
169
SecurityUtils.setSecurityManager(manager);
170
```
171

172
### Specialized Security Manager Implementations
173

174
Additional SecurityManager implementations for specific use cases.
175

176
```java { .api }
177
/**
178
 * SecurityManager implementation that uses a single Realm to do all of its authentication and authorization operations.
179
 */
180
public class RealmSecurityManager extends DefaultSecurityManager {
181
    /**
182
     * Default no-argument constructor that initializes an internal default Realm.
183
     */
184
    public RealmSecurityManager();
185

186
    /**
187
     * Constructs a RealmSecurityManager instance with the single specified Realm.
188
     * @param realm the single Realm to use for authentication and authorization operations
189
     */
190
    public RealmSecurityManager(Realm realm);
191

192
    /**
193
     * Sets the single Realm used by this SecurityManager.
194
     * @param realm the single Realm to use for authentication and authorization operations
195
     */
196
    public void setRealm(Realm realm);
197

198
    /**
199
     * Returns the single Realm used by this SecurityManager.
200
     * @return the single Realm used by this SecurityManager
201
     */
202
    public Realm getRealm();
203
}
204

205
/**
206
 * SecurityManager implementation that only provides authentication capabilities.
207
 */
208
public class AuthenticatingSecurityManager extends RealmSecurityManager {
209
    public AuthenticatingSecurityManager();
210
    public AuthenticatingSecurityManager(Realm realm);
211
}
212

213
/**
214
 * SecurityManager implementation that provides both authentication and authorization capabilities.
215
 */
216
public class AuthorizingSecurityManager extends AuthenticatingSecurityManager {
217
    public AuthorizingSecurityManager();
218
    public AuthorizingSecurityManager(Realm realm);
219
}
220

221
/**
222
 * SecurityManager implementation that provides session management capabilities.
223
 */
224
public class SessionsSecurityManager extends AuthorizingSecurityManager {
225
    public SessionsSecurityManager();
226
    public SessionsSecurityManager(Realm realm);
227
}
228

229
/**
230
 * SecurityManager implementation that provides caching capabilities.
231
 */
232
public class CachingSecurityManager extends SessionsSecurityManager {
233
    public CachingSecurityManager();
234
    public CachingSecurityManager(Realm realm);
235
}
236
```
237

238
### Subject Factory
239

240
Interface and implementation for creating Subject instances.
241

242
```java { .api }
243
/**
244
 * A SubjectFactory creates Subject instances based on contextual information.
245
 */
246
public interface SubjectFactory {
247
    /**
248
     * Creates a new Subject instance reflecting the state specified in the given SubjectContext.
249
     * @param context the context information to use when creating the Subject instance
250
     * @return a new Subject instance reflecting the state specified in the given SubjectContext
251
     */
252
    Subject createSubject(SubjectContext context);
253
}
254

255
/**
256
 * Default SubjectFactory implementation that creates DefaultSubject instances.
257
 */
258
public class DefaultSubjectFactory implements SubjectFactory {
259
    public DefaultSubjectFactory();
260
    
261
    public Subject createSubject(SubjectContext context);
262
}
263
```
264

265
### Subject Context
266

267
Context information used when creating Subject instances.
268

269
```java { .api }
270
/**
271
 * A SubjectContext is a data structure that holds contextual information about a Subject
272
 * that is used to construct Subject instances.
273
 */
274
public interface SubjectContext extends Map<String, Object> {
275
    /**
276
     * Returns the SecurityManager instance that should be used to back the constructed Subject.
277
     * @return the SecurityManager instance that should be used to back the constructed Subject
278
     */
279
    SecurityManager getSecurityManager();
280

281
    /**
282
     * Sets the SecurityManager instance that should be used to back the constructed Subject.
283
     * @param securityManager the SecurityManager instance that should be used to back the constructed Subject
284
     */
285
    void setSecurityManager(SecurityManager securityManager);
286

287
    /**
288
     * Returns the Session that should be associated with the constructed Subject.
289
     * @return the Session that should be associated with the constructed Subject
290
     */
291
    Session getSession();
292

293
    /**
294
     * Sets the Session that should be associated with the constructed Subject.
295
     * @param session the Session that should be associated with the constructed Subject
296
     */
297
    void setSession(Session session);
298

299
    /**
300
     * Returns the principals (identity) that the constructed Subject should reflect.
301
     * @return the principals (identity) that the constructed Subject should reflect
302
     */
303
    PrincipalCollection getPrincipals();
304

305
    /**
306
     * Sets the principals (identity) that the constructed Subject should reflect.
307
     * @param principals the principals (identity) that the constructed Subject should reflect
308
     */
309
    void setPrincipals(PrincipalCollection principals);
310

311
    /**
312
     * Returns true if the constructed Subject should be considered authenticated, false otherwise.
313
     * @return true if the constructed Subject should be considered authenticated, false otherwise
314
     */
315
    boolean isAuthenticated();
316

317
    /**
318
     * Sets whether or not the constructed Subject should be considered authenticated.
319
     * @param authenticated whether or not the constructed Subject should be considered authenticated
320
     */
321
    void setAuthenticated(boolean authenticated);
322
}
323

324
/**
325
 * Default implementation of the SubjectContext interface.
326
 */
327
public class DefaultSubjectContext implements SubjectContext {
328
    public DefaultSubjectContext();
329
    public DefaultSubjectContext(SubjectContext context);
330
}
331
```
332

333
**Usage Example:**
334

335
```java
336
// Custom subject creation
337
DefaultSubjectContext context = new DefaultSubjectContext();
338
context.setSecurityManager(SecurityUtils.getSecurityManager());
339
context.setAuthenticated(true);
340
context.setPrincipals(new SimplePrincipalCollection("username", "realm"));
341

342
Subject customSubject = SecurityUtils.getSecurityManager().createSubject(context);
343

344
// Use custom subject
345
customSubject.execute(() -> {
346
    // Code executing with custom subject context
347
    performOperation();
348
});
349
```
350

351
## Types
352

353
```java { .api }
354
public interface SubjectDAO {
355
    Subject save(Subject subject);
356
    void delete(Subject subject);
357
}
358

359
public class DefaultSubjectDAO implements SubjectDAO {
360
    public DefaultSubjectDAO();
361
    public Subject save(Subject subject);
362
    public void delete(Subject subject);
363
}
364

365
public interface RememberMeManager {
366
    PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext);
367
    void forgetIdentity(SubjectContext subjectContext);
368
    void onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info);
369
    void onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae);
370
    void onLogout(Subject subject);
371
}
372
```