0
# Authorization
1

2
Apache Shiro's authorization framework provides comprehensive access control through role-based and permission-based authorization. It supports wildcard permissions, annotation-driven security, and flexible authorization policies that can be applied at both programmatic and declarative levels.
3

4
## Capabilities
5

6
### Authorization Core Interface
7

8
The primary interface for performing authorization operations.
9

10
```java { .api }
11
/**
12
 * An Authorizer performs authorization (access control) operations for any given Subject.
13
 */
14
public interface Authorizer {
15
    /**
16
     * Returns true if the corresponding Subject is permitted to perform an action or access a resource.
17
     * @param principals the application-specific subject/user identifier
18
     * @param permission the permission being checked
19
     * @return true if permitted, false otherwise
20
     */
21
    boolean isPermitted(PrincipalCollection principals, String permission);
22

23
    /**
24
     * Returns true if the corresponding Subject is permitted to perform an action or access a resource.
25
     * @param principals the application-specific subject/user identifier
26
     * @param permission the permission being checked
27
     * @return true if permitted, false otherwise
28
     */
29
    boolean isPermitted(PrincipalCollection principals, Permission permission);
30

31
    /**
32
     * Returns true if the corresponding Subject has the specified role.
33
     * @param principals the application-specific subject/user identifier
34
     * @param roleIdentifier the application-specific role identifier
35
     * @return true if the subject has the specified role, false otherwise
36
     */
37
    boolean hasRole(PrincipalCollection principals, String roleIdentifier);
38

39
    /**
40
     * Ensures the corresponding Subject is permitted to perform an action or access a resource.
41
     * @param principals the application-specific subject/user identifier
42
     * @param permission the permission being checked
43
     * @throws AuthorizationException if the subject is not permitted
44
     */
45
    void checkPermission(PrincipalCollection principals, String permission) throws AuthorizationException;
46

47
    /**
48
     * Ensures the corresponding Subject is permitted to perform an action or access a resource.
49
     * @param principals the application-specific subject/user identifier
50
     * @param permission the permission being checked
51
     * @throws AuthorizationException if the subject is not permitted
52
     */
53
    void checkPermission(PrincipalCollection principals, Permission permission) throws AuthorizationException;
54

55
    /**
56
     * Ensures the corresponding Subject has the specified role.
57
     * @param principals the application-specific subject/user identifier
58
     * @param roleIdentifier the application-specific role identifier
59
     * @throws AuthorizationException if the subject does not have the specified role
60
     */
61
    void checkRole(PrincipalCollection principals, String roleIdentifier) throws AuthorizationException;
62
}
63

64
/**
65
 * Authorizer implementation that uses configured realms to perform authorization operations.
66
 */
67
public class ModularRealmAuthorizer implements Authorizer, PermissionResolverAware, RolePermissionResolverAware {
68
    /**
69
     * Sets the realms used by this Authorizer.
70
     * @param realms the realms used for authorization operations
71
     */
72
    public void setRealms(Collection<Realm> realms);
73

74
    /**
75
     * Returns the realms used by this Authorizer.
76
     * @return the realms used for authorization operations
77
     */
78
    public Collection<Realm> getRealms();
79

80
    /**
81
     * Sets the PermissionResolver used to resolve strings into Permission instances.
82
     * @param permissionResolver the PermissionResolver to use
83
     */
84
    public void setPermissionResolver(PermissionResolver permissionResolver);
85

86
    /**
87
     * Sets the RolePermissionResolver used to resolve role strings into Permission instances.
88
     * @param rolePermissionResolver the RolePermissionResolver to use
89
     */
90
    public void setRolePermissionResolver(RolePermissionResolver rolePermissionResolver);
91
}
92
```
93

94
### Authorization Info
95

96
Authorization information provided by realms.
97

98
```java { .api }
99
/**
100
 * AuthorizationInfo represents a single Subject's stored authorization data (roles, permissions, etc).
101
 */
102
public interface AuthorizationInfo extends Serializable {
103
    /**
104
     * Returns the names of all roles that are granted to the corresponding Subject.
105
     * @return the names of all roles that are granted to the corresponding Subject
106
     */
107
    Collection<String> getRoles();
108

109
    /**
110
     * Returns the names of all string-based permissions granted to the corresponding Subject.
111
     * @return the names of all string-based permissions granted to the corresponding Subject
112
     */
113
    Collection<String> getStringPermissions();
114

115
    /**
116
     * Returns all object-based permissions granted to the corresponding Subject.
117
     * @return all object-based permissions granted to the corresponding Subject
118
     */
119
    Collection<Permission> getObjectPermissions();
120
}
121

122
/**
123
 * Simple implementation of the AuthorizationInfo interface.
124
 */
125
public class SimpleAuthorizationInfo implements AuthorizationInfo {
126
    public SimpleAuthorizationInfo();
127

128
    /**
129
     * Constructor that accepts a set of roles.
130
     * @param roles the set of roles granted to the corresponding Subject
131
     */
132
    public SimpleAuthorizationInfo(Set<String> roles);
133

134
    /**
135
     * Adds (assigns) a role to the corresponding Subject.
136
     * @param role the role to add
137
     */
138
    public void addRole(String role);
139

140
    /**
141
     * Adds (assigns) multiple roles to the corresponding Subject.
142
     * @param roles the roles to add
143
     */
144
    public void addRoles(Collection<String> roles);
145

146
    /**
147
     * Adds (assigns) a permission to the corresponding Subject.
148
     * @param permission the permission to add
149
     */
150
    public void addStringPermission(String permission);
151

152
    /**
153
     * Adds (assigns) multiple string-based permissions to the corresponding Subject.
154
     * @param permissions the permissions to add
155
     */
156
    public void addStringPermissions(Collection<String> permissions);
157

158
    /**
159
     * Adds (assigns) an object permission to the corresponding Subject.
160
     * @param permission the permission to add
161
     */
162
    public void addObjectPermission(Permission permission);
163

164
    /**
165
     * Adds (assigns) multiple object permissions to the corresponding Subject.
166
     * @param permissions the permissions to add
167
     */
168
    public void addObjectPermissions(Collection<Permission> permissions);
169
}
170
```
171

172
### Permission System
173

174
Apache Shiro's flexible permission system supporting various permission models.
175

176
```java { .api }
177
/**
178
 * A Permission represents the ability to perform an action or access a resource.
179
 */
180
public interface Permission {
181
    /**
182
     * Returns true if this current instance implies all the functionality and/or resource access described by the specified Permission argument.
183
     * @param p the permission to check for behavior/functionality comparison
184
     * @return true if this current instance implies all the functionality and/or resource access described by the specified Permission argument
185
     */
186
    boolean implies(Permission p);
187
}
188

189
/**
190
 * A very powerful and flexible permission implementation based on Ant-style path expressions.
191
 */
192
public class WildcardPermission implements Permission {
193
    /**
194
     * Constructor accepting a wildcard string.
195
     * @param wildcardString the wildcard string to parse
196
     */
197
    public WildcardPermission(String wildcardString);
198

199
    /**
200
     * Constructor accepting a wildcard string and case sensitivity flag.
201
     * @param wildcardString the wildcard string to parse
202
     * @param caseSensitive whether the permission should be case sensitive
203
     */
204
    public WildcardPermission(String wildcardString, boolean caseSensitive);
205

206
    public boolean implies(Permission p);
207

208
    public String toString();
209
}
210

211
/**
212
 * An all-allowing permission that grants access to everything.
213
 */
214
public class AllPermission implements Permission {
215
    public AllPermission();
216
    public boolean implies(Permission p);
217
}
218

219
/**
220
 * Interface for components that can resolve permission strings into Permission objects.
221
 */
222
public interface PermissionResolver {
223
    /**
224
     * Resolves a permission string into a Permission object.
225
     * @param permissionString the permission string to resolve
226
     * @return a Permission object representing the specified string
227
     */
228
    Permission resolvePermission(String permissionString);
229
}
230

231
/**
232
 * Default implementation that creates WildcardPermission instances from permission strings.
233
 */
234
public class WildcardPermissionResolver implements PermissionResolver {
235
    public WildcardPermissionResolver();
236
    
237
    public Permission resolvePermission(String permissionString);
238
}
239

240
/**
241
 * Interface implemented by components that need to be aware of the system's PermissionResolver.
242
 */
243
public interface PermissionResolverAware {
244
    /**
245
     * Sets the PermissionResolver to be used by this component.
246
     * @param pr the PermissionResolver to use
247
     */
248
    void setPermissionResolver(PermissionResolver pr);
249
}
250
```
251

252
**Usage Examples:**
253

254
```java
255
// Wildcard permissions
256
WildcardPermission userPerm = new WildcardPermission("user:*");
257
WildcardPermission specificPerm = new WildcardPermission("user:create:123");
258

259
// Check if broader permission implies more specific one
260
if (userPerm.implies(specificPerm)) {
261
    System.out.println("User permission allows creation of user 123");
262
}
263

264
// Permission examples:
265
// "file:read" - read any file
266
// "file:read,write" - read and write any file  
267
// "file:read:*" - read any file
268
// "file:read:/documents/*" - read any file in documents directory
269
// "file:read,write:/documents/private" - read and write specific file
270
```
271

272
### Role Permission Resolution
273

274
System for mapping roles to permissions dynamically.
275

276
```java { .api }
277
/**
278
 * Interface for resolving permissions assigned to roles.
279
 */
280
public interface RolePermissionResolver {
281
    /**
282
     * Returns the permissions that the specified role implies.
283
     * @param roleString the application-specific role identifier
284
     * @return the permissions that the specified role implies
285
     */
286
    Collection<Permission> resolvePermissionsInRole(String roleString);
287
}
288

289
/**
290
 * Interface implemented by components that need to be aware of the system's RolePermissionResolver.
291
 */
292
public interface RolePermissionResolverAware {
293
    /**
294
     * Sets the RolePermissionResolver to be used by this component.
295
     * @param rpr the RolePermissionResolver to use
296
     */
297
    void setRolePermissionResolver(RolePermissionResolver rpr);
298
}
299
```
300

301
### Authorization Annotations
302

303
Declarative authorization through method-level annotations.
304

305
```java { .api }
306
/**
307
 * Annotation requiring the current user to be authenticated (not anonymous) in order to access the annotated class/instance/method.
308
 */
309
@Target({ElementType.TYPE, ElementType.METHOD})
310
@Retention(RetentionPolicy.RUNTIME)
311
public @interface RequiresAuthentication {
312
}
313

314
/**
315
 * Annotation requiring the current user to be a "user", meaning they are either remembered from a previous session or authenticated in the current session.
316
 */
317
@Target({ElementType.TYPE, ElementType.METHOD})
318
@Retention(RetentionPolicy.RUNTIME)
319
public @interface RequiresUser {
320
}
321

322
/**
323
 * Annotation requiring the current user to be a "guest", meaning they are not authenticated or remembered from a previous session.
324
 */
325
@Target({ElementType.TYPE, ElementType.METHOD})
326
@Retention(RetentionPolicy.RUNTIME)
327
public @interface RequiresGuest {
328
}
329

330
/**
331
 * Annotation requiring the current Subject to have one or more roles in order to execute the annotated method.
332
 */
333
@Target({ElementType.TYPE, ElementType.METHOD})
334
@Retention(RetentionPolicy.RUNTIME)
335
public @interface RequiresRoles {
336
    /**
337
     * The role identifiers required for the method execution to continue.
338
     * @return the role identifiers required for the method execution to continue
339
     */
340
    String[] value();
341

342
    /**
343
     * The logical operation for combining the required roles.
344
     * @return the logical operation for combining the required roles
345
     */
346
    Logical logical() default Logical.AND;
347
}
348

349
/**
350
 * Annotation requiring the current Subject to have one or more permissions in order to execute the annotated method.
351
 */
352
@Target({ElementType.TYPE, ElementType.METHOD})
353
@Retention(RetentionPolicy.RUNTIME)
354
public @interface RequiresPermissions {
355
    /**
356
     * The permission strings required for the method execution to continue.
357
     * @return the permission strings required for the method execution to continue
358
     */
359
    String[] value();
360

361
    /**
362
     * The logical operation for combining the required permissions.
363
     * @return the logical operation for combining the required permissions
364
     */
365
    Logical logical() default Logical.AND;
366
}
367

368
/**
369
 * Enumeration for specifying logical operations when combining multiple authorization criteria.
370
 */
371
public enum Logical {
372
    AND, OR
373
}
374
```
375

376
**Usage Examples:**
377

378
```java
379
public class UserService {
380
    
381
    @RequiresAuthentication
382
    public void updateProfile(User user) {
383
        // Method requires authenticated user
384
    }
385
    
386
    @RequiresRoles("admin")
387
    public void deleteUser(String userId) {
388
        // Method requires admin role
389
    }
390
    
391
    @RequiresRoles(value = {"admin", "manager"}, logical = Logical.OR)
392
    public void viewReports() {
393
        // Method requires admin OR manager role
394
    }
395
    
396
    @RequiresPermissions("user:create")
397
    public void createUser(User user) {
398
        // Method requires specific permission
399
    }
400
    
401
    @RequiresPermissions(value = {"user:read", "user:write"}, logical = Logical.AND)
402
    public void editUser(String userId, User updates) {
403
        // Method requires both read and write permissions
404
    }
405
    
406
    @RequiresGuest
407
    public void showRegistrationPage() {
408
        // Method only for unauthenticated users
409
    }
410
}
411
```
412

413
### AOP Integration
414

415
Aspect-oriented programming support for method-level authorization.
416

417
```java { .api }
418
/**
419
 * Base class for method interceptors that perform authorization checks.
420
 */
421
public abstract class AuthorizingMethodInterceptor extends AnnotationMethodInterceptor {
422
    /**
423
     * Performs the authorization check before method execution.
424
     * @param methodInvocation the method invocation being intercepted
425
     * @throws AuthorizationException if authorization fails
426
     */
427
    protected abstract void assertAuthorized(MethodInvocation methodInvocation) throws AuthorizationException;
428
}
429

430
/**
431
 * Method interceptor that asserts the calling Subject is authenticated before allowing access.
432
 */
433
public class AuthenticatedMethodInterceptor extends AuthorizingMethodInterceptor {
434
    public AuthenticatedMethodInterceptor();
435
    
436
    protected void assertAuthorized(MethodInvocation mi) throws AuthorizationException;
437
}
438

439
/**
440
 * Method interceptor that asserts the calling Subject has the required roles before allowing access.
441
 */
442
public class RoleMethodInterceptor extends AuthorizingMethodInterceptor {
443
    public RoleMethodInterceptor();
444
    
445
    protected void assertAuthorized(MethodInvocation mi) throws AuthorizationException;
446
}
447

448
/**
449
 * Method interceptor that asserts the calling Subject has the required permissions before allowing access.
450
 */
451
public class PermissionMethodInterceptor extends AuthorizingMethodInterceptor {
452
    public PermissionMethodInterceptor();
453
    
454
    protected void assertAuthorized(MethodInvocation mi) throws AuthorizationException;
455
}
456
```
457

458
## Exception Hierarchy
459

460
```java { .api }
461
/**
462
 * Base exception for all authorization-related problems.
463
 */
464
public class AuthorizationException extends ShiroException {
465
    public AuthorizationException();
466
    public AuthorizationException(String message);
467
    public AuthorizationException(Throwable cause);
468
    public AuthorizationException(String message, Throwable cause);
469
}
470

471
/**
472
 * Exception thrown when a Subject is not authorized to perform a particular action.
473
 */
474
public class UnauthorizedException extends AuthorizationException {
475
    public UnauthorizedException();
476
    public UnauthorizedException(String message);
477
    public UnauthorizedException(Throwable cause);
478
    public UnauthorizedException(String message, Throwable cause);
479
}
480

481
/**
482
 * Exception thrown when a Subject is required to be authenticated but is not.
483
 */
484
public class UnauthenticatedException extends AuthorizationException {
485
    public UnauthenticatedException();
486
    public UnauthenticatedException(String message);
487
    public UnauthenticatedException(Throwable cause);
488
    public UnauthenticatedException(String message, Throwable cause);
489
}
490
```
491

492
## Types
493

494
```java { .api }
495
public interface MethodInvocation {
496
    Object proceed() throws Throwable;
497
    Method getMethod();
498
    Object[] getArguments();
499
    Object getThis();
500
}
501
```