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 java.util.Collection;
022 import java.util.List;
023
024 import org.apache.shiro.subject.PrincipalCollection;
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 * @author Jeremy Haile
047 * @author Les Hazlewood
048 * @since 0.1
049 */
050 public interface Authorizer {
051
052 /**
053 * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
054 * summarized by the specified permission string.
055 *
056 * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
057 * Please see the class-level JavaDoc for more information on these String-based permission methods.
058 *
059 * @param principals the application-specific subject/user identifier.
060 * @param permission the String representation of a Permission that is being checked.
061 * @return true if the corresponding Subject/user is permitted, false otherwise.
062 * @see #isPermitted(PrincipalCollection principals,Permission permission)
063 * @since 0.9
064 */
065 boolean isPermitted(PrincipalCollection principals, String permission);
066
067 /**
068 * Returns <tt>true</tt> if the corresponding subject/user is permitted to perform an action or access a resource
069 * summarized by the specified permission.
070 *
071 * <p>More specifically, this method determines if any <tt>Permission</tt>s associated
072 * with the subject {@link Permission#implies(Permission) imply} the specified permission.
073 *
074 * @param subjectPrincipal the application-specific subject/user identifier.
075 * @param permission the permission that is being checked.
076 * @return true if the corresponding Subject/user is permitted, false otherwise.
077 */
078 boolean isPermitted(PrincipalCollection subjectPrincipal, Permission permission);
079
080 /**
081 * Checks if the corresponding Subject implies the given permission strings and returns a boolean array
082 * indicating which permissions are implied.
083 *
084 * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
085 * Please see the class-level JavaDoc for more information on these String-based permission methods.
086 *
087 * @param subjectPrincipal the application-specific subject/user identifier.
088 * @param permissions the String representations of the Permissions that are being checked.
089 * @return an array of booleans whose indices correspond to the index of the
090 * permissions in the given list. A true value at an index indicates the user is permitted for
091 * for the associated <tt>Permission</tt> string in the list. A false value at an index
092 * indicates otherwise.
093 * @since 0.9
094 */
095 boolean[] isPermitted(PrincipalCollection subjectPrincipal, String... permissions);
096
097 /**
098 * Checks if the corresponding Subject/user implies the given Permissions and returns a boolean array indicating
099 * which permissions are implied.
100 *
101 * <p>More specifically, this method should determine if each <tt>Permission</tt> in
102 * the array is {@link Permission#implies(Permission) implied} by permissions
103 * already associated with the subject.
104 *
105 * <p>This is primarily a performance-enhancing method to help reduce the number of
106 * {@link #isPermitted} invocations over the wire in client/server systems.
107 *
108 * @param subjectPrincipal the application-specific subject/user identifier.
109 * @param permissions the permissions that are being checked.
110 * @return an array of booleans whose indices correspond to the index of the
111 * permissions in the given list. A true value at an index indicates the user is permitted for
112 * for the associated <tt>Permission</tt> object in the list. A false value at an index
113 * indicates otherwise.
114 */
115 boolean[] isPermitted(PrincipalCollection subjectPrincipal, List<Permission> permissions);
116
117 /**
118 * Returns <tt>true</tt> if the corresponding Subject/user implies all of the specified permission strings,
119 * <tt>false</tt> otherwise.
120 *
121 * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
122 * Please see the class-level JavaDoc for more information on these String-based permission methods.
123 *
124 * @param subjectPrincipal the application-specific subject/user identifier.
125 * @param permissions the String representations of the Permissions that are being checked.
126 * @return true if the user has all of the specified permissions, false otherwise.
127 * @see #isPermittedAll(PrincipalCollection,Collection)
128 * @since 0.9
129 */
130 boolean isPermittedAll(PrincipalCollection subjectPrincipal, String... permissions);
131
132 /**
133 * Returns <tt>true</tt> if the corresponding Subject/user implies all of the specified permissions, <tt>false</tt>
134 * otherwise.
135 *
136 * <p>More specifically, this method determines if all of the given <tt>Permission</tt>s are
137 * {@link Permission#implies(Permission) implied by} permissions already associated with the subject.
138 *
139 * @param subjectPrincipal the application-specific subject/user identifier.
140 * @param permissions the permissions to check.
141 * @return true if the user has all of the specified permissions, false otherwise.
142 */
143 boolean isPermittedAll(PrincipalCollection subjectPrincipal, Collection<Permission> permissions);
144
145 /**
146 * Ensures the corresponding Subject/user implies the specified permission String.
147 *
148 * <p>If the subject's existing associated permissions do not {@link Permission#implies(Permission)} imply}
149 * the given permission, an {@link AuthorizationException} will be thrown.
150 *
151 * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
152 * Please see the class-level JavaDoc for more information on these String-based permission methods.
153 *
154 * @param subjectPrincipal the application-specific subject/user identifier.
155 * @param permission the String representation of the Permission to check.
156 * @throws AuthorizationException
157 * if the user does not have the permission.
158 * @since 0.9
159 */
160 void checkPermission(PrincipalCollection subjectPrincipal, String permission) throws AuthorizationException;
161
162 /**
163 * Ensures a subject/user {@link Permission#implies(Permission)} implies} the specified <tt>Permission</tt>.
164 * If the subject's exisiting associated permissions do not {@link Permission#implies(Permission)} imply}
165 * the given permission, an {@link AuthorizationException} will be thrown.
166 *
167 * @param subjectPrincipal the application-specific subject/user identifier.
168 * @param permission the Permission to check.
169 * @throws AuthorizationException
170 * if the user does not have the permission.
171 */
172 void checkPermission(PrincipalCollection subjectPrincipal, Permission permission) throws AuthorizationException;
173
174 /**
175 * Ensures the corresponding Subject/user
176 * {@link Permission#implies(Permission) implies} all of the
177 * specified permission strings.
178 *
179 * If the subject's exisiting associated permissions do not
180 * {@link Permission#implies(Permission) imply} all of the given permissions,
181 * an {@link AuthorizationException} will be thrown.
182 *
183 * <p>This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
184 * Please see the class-level JavaDoc for more information on these String-based permission methods.
185 *
186 * @param subjectPrincipal the application-specific subject/user identifier.
187 * @param permissions the string representations of Permissions to check.
188 * @throws AuthorizationException if the user does not have all of the given permissions.
189 * @since 0.9
190 */
191 void checkPermissions(PrincipalCollection subjectPrincipal, String... permissions) throws AuthorizationException;
192
193 /**
194 * Ensures the corresponding Subject/user
195 * {@link Permission#implies(Permission) implies} all of the
196 * specified permission strings.
197 *
198 * If the subject's exisiting associated permissions do not
199 * {@link Permission#implies(Permission) imply} all of the given permissions,
200 * an {@link AuthorizationException} will be thrown.
201 *
202 * @param subjectPrincipal the application-specific subject/user identifier.
203 * @param permissions the Permissions to check.
204 * @throws AuthorizationException if the user does not have all of the given permissions.
205 */
206 void checkPermissions(PrincipalCollection subjectPrincipal, Collection<Permission> permissions) throws AuthorizationException;
207
208 /**
209 * Returns <tt>true</tt> if the corresponding Subject/user has the specified role, <tt>false</tt> otherwise.
210 *
211 * @param subjectPrincipal the application-specific subject/user identifier.
212 * @param roleIdentifier the application-specific role identifier (usually a role id or role name).
213 * @return <tt>true</tt> if the corresponding subject has the specified role, <tt>false</tt> otherwise.
214 */
215 boolean hasRole(PrincipalCollection subjectPrincipal, String roleIdentifier);
216
217 /**
218 * Checks if the corresponding Subject/user has the specified roles, returning a boolean array indicating
219 * which roles are associated with the given subject.
220 *
221 * <p>This is primarily a performance-enhancing method to help reduce the number of
222 * {@link #hasRole} invocations over the wire in client/server systems.
223 *
224 * @param subjectPrincipal the application-specific subject/user identifier.
225 * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
226 * @return an array of booleans whose indices correspond to the index of the
227 * roles in the given identifiers. A true value indicates the user has the
228 * role at that index. False indicates the user does not have the role at that index.
229 */
230 boolean[] hasRoles(PrincipalCollection subjectPrincipal, List<String> roleIdentifiers);
231
232 /**
233 * Returns <tt>true</tt> if the corresponding Subject/user has all of the specified roles, <tt>false</tt> otherwise.
234 *
235 * @param subjectPrincipal the application-specific subject/user identifier.
236 * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
237 * @return true if the user has all the roles, false otherwise.
238 */
239 boolean hasAllRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers);
240
241 /**
242 * Asserts the corresponding Subject/user has the specified role by returning quietly if they do or throwing an
243 * {@link AuthorizationException} if they do not.
244 *
245 * @param subjectPrincipal the application-specific subject/user identifier.
246 * @param roleIdentifier the application-specific role identifier (usually a role id or role name ).
247 * @throws AuthorizationException
248 * if the user does not have the role.
249 */
250 void checkRole(PrincipalCollection subjectPrincipal, String roleIdentifier) throws AuthorizationException;
251
252 /**
253 * Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or
254 * throwing an {@link AuthorizationException} if they do not.
255 *
256 * @param subjectPrincipal the application-specific subject/user identifier.
257 * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
258 * @throws AuthorizationException
259 * if the user does not have all of the specified roles.
260 */
261 void checkRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers) throws AuthorizationException;
262
263 }
264