View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.shiro.authz;
20  
21  import org.apache.shiro.subject.PrincipalCollection;
22  
23  import java.util.Collection;
24  import java.util.List;
25  
26  /**
27   * An <tt>Authorizer</tt> performs authorization (access control) operations for any given Subject
28   * (aka 'application user').
29   *
30   * <p>Each method requires a subject principal to perform the action for the corresponding Subject/user.
31   *
32   * <p>This principal argument is usually an object representing a user database primary key or a String username or
33   * something similar that uniquely identifies an application user.  The runtime value of the this principal
34   * is application-specific and provided by the application's configured Realms.
35   *
36   * <p>Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of
37   * {@link Permission Permission} instances. They are a convenience allowing the caller to use a String representation of
38   * a {@link Permission Permission} if desired.  Most implementations of this interface will simply convert these
39   * String values to {@link Permission Permission} instances and then just call the corresponding type-safe method.
40   * (Shiro's default implementations do String-to-Permission conversion for these methods using
41   * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}s.)
42   *
43   * <p>These overloaded *Permission methods <em>do</em> forego type-saftey for the benefit of convenience and simplicity,
44   * so you should choose which ones to use based on your preferences and needs.
45   *
46   * @since 0.1
47   */
48  public interface Authorizer {
49  
50      /**
51       * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
52       * summarized by the specified permission string.
53       *
54       * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
55       * Please see the class-level JavaDoc for more information on these String-based permission methods.
56       *
57       * @param principals the application-specific subject/user identifier.
58       * @param permission the String representation of a Permission that is being checked.
59       * @return true if the corresponding Subject/user is permitted, false otherwise.
60       * @see #isPermitted(PrincipalCollection principals,Permission permission)
61       * @since 0.9
62       */
63      boolean isPermitted(PrincipalCollection principals, String permission);
64  
65      /**
66       * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
67       * summarized by the specified permission.
68       *
69       * <p>More specifically, this method determines if any <tt>Permission</tt>s associated
70       * with the subject {@link Permission#implies(Permission) imply} the specified permission.
71       *
72       * @param subjectPrincipal the application-specific subject/user identifier.
73       * @param permission       the permission that is being checked.
74       * @return true if the corresponding Subject/user is permitted, false otherwise.
75       */
76      boolean isPermitted(PrincipalCollection subjectPrincipal, Permission permission);
77  
78      /**
79       * Checks if the corresponding Subject implies the given permission strings and returns a boolean array
80       * indicating which permissions are implied.
81       *
82       * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
83       * Please see the class-level JavaDoc for more information on these String-based permission methods.
84       *
85       * @param subjectPrincipal the application-specific subject/user identifier.
86       * @param permissions      the String representations of the Permissions that are being checked.
87       * @return an array of booleans whose indices correspond to the index of the
88       *         permissions in the given list.  A true value at an index indicates the user is permitted for
89       *         for the associated <tt>Permission</tt> string in the list.  A false value at an index
90       *         indicates otherwise.
91       * @since 0.9
92       */
93      boolean[] isPermitted(PrincipalCollection subjectPrincipal, String... permissions);
94  
95      /**
96       * Checks if the corresponding Subject/user implies the given Permissions and returns a boolean array indicating
97       * which permissions are implied.
98       *
99       * <p>More specifically, this method should determine if each <tt>Permission</tt> in
100      * the array is {@link Permission#implies(Permission) implied} by permissions
101      * already associated with the subject.
102      *
103      * <p>This is primarily a performance-enhancing method to help reduce the number of
104      * {@link #isPermitted} invocations over the wire in client/server systems.
105      *
106      * @param subjectPrincipal the application-specific subject/user identifier.
107      * @param permissions      the permissions that are being checked.
108      * @return an array of booleans whose indices correspond to the index of the
109      *         permissions in the given list.  A true value at an index indicates the user is permitted for
110      *         for the associated <tt>Permission</tt> object in the list.  A false value at an index
111      *         indicates otherwise.
112      */
113     boolean[] isPermitted(PrincipalCollection subjectPrincipal, List<Permission> permissions);
114 
115     /**
116      * Returns <tt>true</tt> if the corresponding Subject/user implies all of the specified permission strings,
117      * <tt>false</tt> otherwise.
118      *
119      * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
120      * Please see the class-level JavaDoc for more information on these String-based permission methods.
121      *
122      * @param subjectPrincipal the application-specific subject/user identifier.
123      * @param permissions      the String representations of the Permissions that are being checked.
124      * @return true if the user has all of the specified permissions, false otherwise.
125      * @see #isPermittedAll(PrincipalCollection,Collection)
126      * @since 0.9
127      */
128     boolean isPermittedAll(PrincipalCollection subjectPrincipal, String... permissions);
129 
130     /**
131      * Returns <tt>true</tt> if the corresponding Subject/user implies all of the specified permissions, <tt>false</tt>
132      * otherwise.
133      *
134      * <p>More specifically, this method determines if all of the given <tt>Permission</tt>s are
135      * {@link Permission#implies(Permission) implied by} permissions already associated with the subject.
136      *
137      * @param subjectPrincipal the application-specific subject/user identifier.
138      * @param permissions      the permissions to check.
139      * @return true if the user has all of the specified permissions, false otherwise.
140      */
141     boolean isPermittedAll(PrincipalCollection subjectPrincipal, Collection<Permission> permissions);
142 
143     /**
144      * Ensures the corresponding Subject/user implies the specified permission String.
145      *
146      * <p>If the subject's existing associated permissions do not {@link Permission#implies(Permission)} imply}
147      * the given permission, an {@link AuthorizationException} will be thrown.
148      *
149      * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
150      * Please see the class-level JavaDoc for more information on these String-based permission methods.
151      *
152      * @param subjectPrincipal the application-specific subject/user identifier.
153      * @param permission       the String representation of the Permission to check.
154      * @throws AuthorizationException
155      *          if the user does not have the permission.
156      * @since 0.9
157      */
158     void checkPermission(PrincipalCollection subjectPrincipal, String permission) throws AuthorizationException;
159 
160     /**
161      * Ensures a subject/user {@link Permission#implies(Permission)} implies} the specified <tt>Permission</tt>.
162      * If the subject's exisiting associated permissions do not {@link Permission#implies(Permission)} imply}
163      * the given permission, an {@link AuthorizationException} will be thrown.
164      *
165      * @param subjectPrincipal the application-specific subject/user identifier.
166      * @param permission       the Permission to check.
167      * @throws AuthorizationException
168      *          if the user does not have the permission.
169      */
170     void checkPermission(PrincipalCollection subjectPrincipal, Permission permission) throws AuthorizationException;
171 
172     /**
173      * Ensures the corresponding Subject/user
174      * {@link Permission#implies(Permission) implies} all of the
175      * specified permission strings.
176      *
177      * If the subject's exisiting associated permissions do not
178      * {@link Permission#implies(Permission) imply} all of the given permissions,
179      * an {@link AuthorizationException} will be thrown.
180      *
181      * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
182      * Please see the class-level JavaDoc for more information on these String-based permission methods.
183      *
184      * @param subjectPrincipal the application-specific subject/user identifier.
185      * @param permissions      the string representations of Permissions to check.
186      * @throws AuthorizationException if the user does not have all of the given permissions.
187      * @since 0.9
188      */
189     void checkPermissions(PrincipalCollection subjectPrincipal, String... permissions) throws AuthorizationException;
190 
191     /**
192      * Ensures the corresponding Subject/user
193      * {@link Permission#implies(Permission) implies} all of the
194      * specified permission strings.
195      *
196      * If the subject's exisiting associated permissions do not
197      * {@link Permission#implies(Permission) imply} all of the given permissions,
198      * an {@link AuthorizationException} will be thrown.
199      *
200      * @param subjectPrincipal the application-specific subject/user identifier.
201      * @param permissions      the Permissions to check.
202      * @throws AuthorizationException if the user does not have all of the given permissions.
203      */
204     void checkPermissions(PrincipalCollection subjectPrincipal, Collection<Permission> permissions) throws AuthorizationException;
205 
206     /**
207      * Returns <tt>true</tt> if the corresponding Subject/user has the specified role, <tt>false</tt> otherwise.
208      *
209      * @param subjectPrincipal the application-specific subject/user identifier.
210      * @param roleIdentifier   the application-specific role identifier (usually a role id or role name).
211      * @return <tt>true</tt> if the corresponding subject has the specified role, <tt>false</tt> otherwise.
212      */
213     boolean hasRole(PrincipalCollection subjectPrincipal, String roleIdentifier);
214 
215     /**
216      * Checks if the corresponding Subject/user has the specified roles, returning a boolean array indicating
217      * which roles are associated with the given subject.
218      *
219      * <p>This is primarily a performance-enhancing method to help reduce the number of
220      * {@link #hasRole} invocations over the wire in client/server systems.
221      *
222      * @param subjectPrincipal the application-specific subject/user identifier.
223      * @param roleIdentifiers  the application-specific role identifiers to check (usually role ids or role names).
224      * @return an array of booleans whose indices correspond to the index of the
225      *         roles in the given identifiers.  A true value indicates the user has the
226      *         role at that index.  False indicates the user does not have the role at that index.
227      */
228     boolean[] hasRoles(PrincipalCollection subjectPrincipal, List<String> roleIdentifiers);
229 
230     /**
231      * Returns <tt>true</tt> if the corresponding Subject/user has all of the specified roles, <tt>false</tt> otherwise.
232      *
233      * @param subjectPrincipal the application-specific subject/user identifier.
234      * @param roleIdentifiers  the application-specific role identifiers to check (usually role ids or role names).
235      * @return true if the user has all the roles, false otherwise.
236      */
237     boolean hasAllRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers);
238 
239     /**
240      * Asserts the corresponding Subject/user has the specified role by returning quietly if they do or throwing an
241      * {@link AuthorizationException} if they do not.
242      *
243      * @param subjectPrincipal the application-specific subject/user identifier.
244      * @param roleIdentifier   the application-specific role identifier (usually a role id or role name ).
245      * @throws AuthorizationException
246      *          if the user does not have the role.
247      */
248     void checkRole(PrincipalCollection subjectPrincipal, String roleIdentifier) throws AuthorizationException;
249 
250     /**
251      * Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or
252      * throwing an {@link AuthorizationException} if they do not.
253      *
254      * @param subjectPrincipal the application-specific subject/user identifier.
255      * @param roleIdentifiers  the application-specific role identifiers to check (usually role ids or role names).
256      * @throws AuthorizationException
257      *          if the user does not have all of the specified roles.
258      */
259     void checkRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers) throws AuthorizationException;
260 
261     /**
262      * Same as {@link #checkRoles(org.apache.shiro.subject.PrincipalCollection, java.util.Collection)
263      * checkRoles(PrincipalCollection subjectPrincipal, Collection&lt;String&gt; roleIdentifiers)} but doesn't require a collection
264      * as an argument.
265      * Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or
266      * throwing an {@link AuthorizationException} if they do not.
267      *
268      * @param subjectPrincipal the application-specific subject/user identifier.
269      * @param roleIdentifiers  the application-specific role identifiers to check (usually role ids or role names).
270      * @throws AuthorizationException
271      *          if the user does not have all of the specified roles.
272      *          
273      *  @since 1.1.0
274      */
275     void checkRoles(PrincipalCollection subjectPrincipal, String... roleIdentifiers) throws AuthorizationException;
276     
277 }
278