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 */
019package org.apache.shiro.authz;
020
021import org.apache.shiro.subject.PrincipalCollection;
022
023import java.util.Collection;
024import 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 */
048public 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