public interface AccessController
The implementation of this interface will need to access the current User object (from Authenticator.getCurrentUser()) to determine roles or permissions. In addition, the implementation will also need information about the resources that are being accessed. Using the user information and the resource information, the implementation should return an access control decision.
Implementers are encouraged to implement the ESAPI access control rules, like assertAuthorizedForFunction() using existing access control mechanisms, such as methods like isUserInRole() or hasPrivilege(). While powerful, methods like isUserInRole() can be confusing for developers, as users may be in multiple roles or possess multiple overlapping privileges. Direct use of these finer grained access control methods encourages the use of complex boolean tests throughout the code, which can easily lead to developer mistakes.
The point of the ESAPI access control interface is to centralize access control logic behind easy to use calls like assertAuthorized() so that access control is easy to use and easy to verify. Here is an example of a very straightforward to implement, understand, and verify ESAPI access control check:
try { ESAPI.accessController().assertAuthorized("businessFunction", runtimeData); // execute BUSINESS_FUNCTION } catch (AccessControlException ace) { ... attack in progress }Note that in the user interface layer, access control checks can be used to control whether particular controls are rendered or not. These checks are supposed to fail when an unauthorized user is logged in, and do not represent attacks. Remember that regardless of how the user interface appears, an attacker can attempt to invoke any business function or access any data in your application. Therefore, access control checks in the user interface should be repeated in both the business logic and data layers.
<% if ( ESAPI.accessController().isAuthorized( "businessFunction", runtimeData ) ) { %> <a href="/doAdminFunction">ADMIN</a> <% } else { %> <a href="/doNormalFunction">NORMAL</a> <% } %>
Modifier and Type | Method and Description |
---|---|
void |
assertAuthorized(Object key,
Object runtimeParameter)
assertAuthorized executes the AccessControlRule
that is identified by key and listed in the
resources/ESAPI-AccessControlPolicy.xml file. |
void |
assertAuthorizedForData(String action,
Object data)
Deprecated.
|
void |
assertAuthorizedForFile(String filepath)
Deprecated.
|
void |
assertAuthorizedForFunction(String functionName)
Deprecated.
|
void |
assertAuthorizedForService(String serviceName)
Deprecated.
|
void |
assertAuthorizedForURL(String url)
Deprecated.
|
boolean |
isAuthorized(Object key,
Object runtimeParameter)
isAuthorized executes the AccessControlRule
that is identified by key and listed in the
resources/ESAPI-AccessControlPolicy.xml file. |
boolean |
isAuthorizedForData(String action,
Object data)
Deprecated.
|
boolean |
isAuthorizedForFile(String filepath)
Deprecated.
|
boolean |
isAuthorizedForFunction(String functionName)
Deprecated.
|
boolean |
isAuthorizedForService(String serviceName)
Deprecated.
|
boolean |
isAuthorizedForURL(String url)
Deprecated.
|
boolean isAuthorized(Object key, Object runtimeParameter)
isAuthorized
executes the AccessControlRule
that is identified by key
and listed in the
resources/ESAPI-AccessControlPolicy.xml
file. It returns
true if the AccessControlRule
decides that the operation
should be allowed. Otherwise, it returns false. Any exception thrown by
the AccessControlRule
must result in false. If
key
does not map to an AccessControlRule
, then
false is returned.
Developers should call isAuthorized to control execution flow. For
example, if you want to decide whether to display a UI widget in the
browser using the same logic that you will use to enforce permissions
on the server, then isAuthorized is the method that you want to use.
Typically, assertAuthorized should be used to enforce permissions on the
server.key
- key
maps to
<AccessControlPolicy><AccessControlRules>
<AccessControlRule name="key"
runtimeParameter
- runtimeParameter can contain anything that
the AccessControlRule needs from the runtime system.true
if and only if the AccessControlRule specified
by key
exists and returned true
.
Otherwise returns false
void assertAuthorized(Object key, Object runtimeParameter) throws AccessControlException
assertAuthorized
executes the AccessControlRule
that is identified by key
and listed in the
resources/ESAPI-AccessControlPolicy.xml
file. It does
nothing if the AccessControlRule
decides that the operation
should be allowed. Otherwise, it throws an
org.owasp.esapi.errors.AccessControlException
. Any exception
thrown by the AccessControlRule
will also result in an
AccesControlException
. If key
does not map to
an AccessControlRule
, then an AccessControlException
is thrown.
Developers should call assertAuthorized
to enforce privileged access to
the system. It should be used to answer the question: "Should execution
continue." Ideally, the call to assertAuthorized
should
be integrated into the application framework so that it is called
automatically.key
- key
maps to
<AccessControlPolicy><AccessControlRules>
<AccessControlRule name="key"runtimeParameter
- runtimeParameter can contain anything that
the AccessControlRule needs from the runtime system.AccessControlException
@Deprecated boolean isAuthorizedForURL(String url)
ESAPI.accessController().isAuthorizedForURL(request.getRequestURI().toString());The implementation of this method should call assertAuthorizedForURL(String url), and if an AccessControlException is not thrown, this method should return true. This way, if the user is not authorized, false would be returned, and the exception would be logged.
url
- the URL as returned by request.getRequestURI().toString()@Deprecated boolean isAuthorizedForFunction(String functionName)
functionName
- the name of the function@Deprecated boolean isAuthorizedForData(String action, Object data)
action
- The action to verify for an access control decision, such as a role, or an action being performed on the object
(e.g., Read, Write, etc.), or the name of the function the data is being passed to.data
- The actual object or object identifier being accessed or a reference to the object being accessed.@Deprecated boolean isAuthorizedForFile(String filepath)
filepath
- the path of the file to be checked, including filename@Deprecated boolean isAuthorizedForService(String serviceName)
serviceName
- the service name@Deprecated void assertAuthorizedForURL(String url) throws AccessControlException
ESAPI.accessController().assertAuthorizedForURL(request.getRequestURI().toString());This method throws an AccessControlException if access is not authorized, or if the referenced URL does not exist. If the User is authorized, this method simply returns.
Specification: The implementation should do the following:
url
- the URL as returned by request.getRequestURI().toString()AccessControlException
- if access is not permitted@Deprecated void assertAuthorizedForFunction(String functionName) throws AccessControlException
This method throws an AccessControlException if access is not authorized, or if the referenced function does not exist. If the User is authorized, this method simply returns.
Specification: The implementation should do the following:
functionName
- the function nameAccessControlException
- if access is not permitted@Deprecated void assertAuthorizedForData(String action, Object data) throws AccessControlException
Specification: The implementation should do the following:
action
- The action to verify for an access control decision, such as a role, or an action being performed on the object
(e.g., Read, Write, etc.), or the name of the function the data is being passed to.data
- The actual object or object identifier being accessed or a reference to the object being accessed.AccessControlException
- if access is not permitted@Deprecated void assertAuthorizedForFile(String filepath) throws AccessControlException
This method throws an AccessControlException if access is not authorized, or if the referenced File does not exist. If the User is authorized, this method simply returns.
Specification: The implementation should do the following:
filepath
- Path to the file to be checkedAccessControlException
- if access is denied@Deprecated void assertAuthorizedForService(String serviceName) throws AccessControlException
This method throws an AccessControlException if access is not authorized, or if the referenced service does not exist. If the User is authorized, this method simply returns.
Specification: The implementation should do the following:
serviceName
- the service nameAccessControlException
- if access is not permittedCopyright © 2021 The Open Web Application Security Project (OWASP). All rights reserved.