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