|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface AccessController
The AccessController interface defines a set of methods that can be used in a wide variety of applications to enforce access control. In most applications, access control must be performed in multiple different locations across the various application layers. This class provides access control for URLs, business functions, data, services, and files.
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> <% } %>
Method Summary | |
---|---|
void |
assertAuthorized(java.lang.Object key,
java.lang.Object runtimeParameter)
assertAuthorized executes the AccessControlRule
that is identified by key and listed in the
resources/ESAPI-AccessControlPolicy.xml file. |
void |
assertAuthorizedForData(java.lang.String action,
java.lang.Object data)
Checks if the current user is authorized to access the referenced data. |
void |
assertAuthorizedForFile(java.lang.String filepath)
Checks if the current user is authorized to access the referenced file. |
void |
assertAuthorizedForFunction(java.lang.String functionName)
Checks if the current user is authorized to access the referenced function. |
void |
assertAuthorizedForService(java.lang.String serviceName)
Checks if the current user is authorized to access the referenced service. |
void |
assertAuthorizedForURL(java.lang.String url)
Checks if the current user is authorized to access the referenced URL. |
boolean |
isAuthorized(java.lang.Object key,
java.lang.Object runtimeParameter)
isAuthorized executes the AccessControlRule
that is identified by key and listed in the
resources/ESAPI-AccessControlPolicy.xml file. |
boolean |
isAuthorizedForData(java.lang.String action,
java.lang.Object data)
Checks if the current user is authorized to access the referenced data, represented as an Object. |
boolean |
isAuthorizedForFile(java.lang.String filepath)
Checks if the current user is authorized to access the referenced file. |
boolean |
isAuthorizedForFunction(java.lang.String functionName)
Checks if the current user is authorized to access the referenced function. |
boolean |
isAuthorizedForService(java.lang.String serviceName)
Checks if the current user is authorized to access the referenced service. |
boolean |
isAuthorizedForURL(java.lang.String url)
Checks if the current user is authorized to access the referenced URL. |
Method Detail |
---|
boolean isAuthorized(java.lang.Object key, java.lang.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(java.lang.Object key, java.lang.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
boolean isAuthorizedForURL(java.lang.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()
boolean isAuthorizedForFunction(java.lang.String functionName)
functionName
- the name of the function
boolean isAuthorizedForData(java.lang.String action, java.lang.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.
boolean isAuthorizedForFile(java.lang.String filepath)
filepath
- the path of the file to be checked, including filename
boolean isAuthorizedForService(java.lang.String serviceName)
serviceName
- the service name
void assertAuthorizedForURL(java.lang.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 permittedvoid assertAuthorizedForFunction(java.lang.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 name
AccessControlException
- if access is not permittedvoid assertAuthorizedForData(java.lang.String action, java.lang.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 permittedvoid assertAuthorizedForFile(java.lang.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 checked
AccessControlException
- if access is deniedvoid assertAuthorizedForService(java.lang.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 name
AccessControlException
- if access is not permitted
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |