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-safety 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 existing 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 existing 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 existing 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<String> 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