001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.authz;
020    
021    import org.apache.shiro.subject.PrincipalCollection;
022    
023    import java.util.Collection;
024    import java.util.List;
025    
026    /**
027     * An <tt>Authorizer</tt> performs authorization (access control) operations for any given Subject
028     * (aka 'application user').
029     *
030     * <p>Each method requires a subject principal to perform the action for the corresponding Subject/user.
031     *
032     * <p>This principal argument is usually an object representing a user database primary key or a String username or
033     * something similar that uniquely identifies an application user.  The runtime value of the this principal
034     * is application-specific and provided by the application's configured Realms.
035     *
036     * <p>Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of
037     * {@link Permission Permission} instances. They are a convenience allowing the caller to use a String representation of
038     * a {@link Permission Permission} if desired.  Most implementations of this interface will simply convert these
039     * String values to {@link Permission Permission} instances and then just call the corresponding type-safe method.
040     * (Shiro's default implementations do String-to-Permission conversion for these methods using
041     * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}s.)
042     *
043     * <p>These overloaded *Permission methods <em>do</em> forego type-saftey for the benefit of convenience and simplicity,
044     * so you should choose which ones to use based on your preferences and needs.
045     *
046     * @since 0.1
047     */
048    public interface Authorizer {
049    
050        /**
051         * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
052         * summarized by the specified permission string.
053         *
054         * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
055         * Please see the class-level JavaDoc for more information on these String-based permission methods.
056         *
057         * @param principals the application-specific subject/user identifier.
058         * @param permission the String representation of a Permission that is being checked.
059         * @return true if the corresponding Subject/user is permitted, false otherwise.
060         * @see #isPermitted(PrincipalCollection principals,Permission permission)
061         * @since 0.9
062         */
063        boolean isPermitted(PrincipalCollection principals, String permission);
064    
065        /**
066         * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
067         * summarized by the specified permission.
068         *
069         * <p>More specifically, this method determines if any <tt>Permission</tt>s associated
070         * with the subject {@link Permission#implies(Permission) imply} the specified permission.
071         *
072         * @param subjectPrincipal the application-specific subject/user identifier.
073         * @param permission       the permission that is being checked.
074         * @return true if the corresponding Subject/user is permitted, false otherwise.
075         */
076        boolean isPermitted(PrincipalCollection subjectPrincipal, Permission permission);
077    
078        /**
079         * Checks if the corresponding Subject implies the given permission strings and returns a boolean array
080         * indicating which permissions are implied.
081         *
082         * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
083         * Please see the class-level JavaDoc for more information on these String-based permission methods.
084         *
085         * @param subjectPrincipal the application-specific subject/user identifier.
086         * @param permissions      the String representations of the Permissions that are being checked.
087         * @return an array of booleans whose indices correspond to the index of the
088         *         permissions in the given list.  A true value at an index indicates the user is permitted for
089         *         for the associated <tt>Permission</tt> string in the list.  A false value at an index
090         *         indicates otherwise.
091         * @since 0.9
092         */
093        boolean[] isPermitted(PrincipalCollection subjectPrincipal, String... permissions);
094    
095        /**
096         * Checks if the corresponding Subject/user implies the given Permissions and returns a boolean array indicating
097         * which permissions are implied.
098         *
099         * <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