org.owasp.esapi.reference.accesscontrol

Class FileBasedACRs

java.lang.Object

org.owasp.esapi.reference.accesscontrol.FileBasedACRs

public class FileBasedACRs
extends java.lang.Object

This class exists for backwards compatibility with the AccessController 1.0 reference implementation. This reference implementation uses a simple model for specifying a set of access control rules. Many organizations will want to create their own implementation of the methods provided in the AccessController interface.

This reference implementation uses a simple scheme for specifying the rules. The first step is to create a namespace for the resources being accessed. For files and URL's, this is easy as they already have a namespace. Be extremely careful about canonicalizing when relying on information from the user in an access control decision.

For functions, data, and services, you will have to come up with your own namespace for the resources being accessed. You might simply define a flat namespace with a list of category names. For example, you might specify 'FunctionA', 'FunctionB', and 'FunctionC'. Or you can create a richer namespace with a hierarchical structure, such as:

/functions

• purchasing
• shipping
• inventory

/admin

• createUser
• deleteUser

Once you've defined your namespace, you have to work out the rules that govern access to the different parts of the namespace. This implementation allows you to attach a simple access control list (ACL) to any part of the namespace tree. The ACL lists a set of roles that are either allowed or denied access to a part of the tree. You specify these rules in a textfile with a simple format.

There is a single configuration file supporting each of the five methods in the AccessController interface. These files are located in the ESAPI resources directory as specified when the JVM was started. The use of a default deny rule is STRONGLY recommended. The file format is as follows:

 path          | role,role   | allow/deny | comment
 ------------------------------------------------------------------------------------
 /banking/*    | user,admin  | allow      | authenticated users can access /banking
 /admin        | admin       | allow      | only admin role can access /admin
 /             | any         | deny       | default deny rule
 

To find the matching rules, this implementation follows the general approach used in Java EE when matching HTTP requests to servlets in web.xml. The four mapping rules are used in the following order:

• exact match, e.g. /access/login
• longest path prefix match, beginning / and ending /*, e.g. /access/* or /*
• extension match, beginning *., e.g. *.css
• default rule, specified by the single character pattern /

Since:

June 1, 2007

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	FileBasedACRs.Rule The Class Rule.

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map	dataMap The data map.
private FileBasedACRs.Rule	deny A rule containing "deny".
private java.util.Map	fileMap The file map.
private java.util.Map	functionMap The function map.
private Logger	logger The logger.
private java.util.Map	serviceMap The service map.
private java.util.Map	urlMap The url map.

Constructor Summary

Constructors

Constructor and Description
FileBasedACRs()

Method Summary

Modifier and Type	Method and Description
private java.util.List	commaSplit(java.lang.String input) This method splits a String by the ',' and returns the result as a List.
boolean	isAuthorizedForData(java.lang.String action, java.lang.Object data) TODO Javadoc
boolean	isAuthorizedForFile(java.lang.String filepath) TODO Javadoc
boolean	isAuthorizedForFunction(java.lang.String functionName) TODO Javadoc
boolean	isAuthorizedForService(java.lang.String serviceName) TODO Javadoc
boolean	isAuthorizedForURL(java.lang.String url) Check if URL is authorized.
private java.util.Map	loadDataRules(java.lang.String ruleset) Loads access rules by storing them in a hashmap.
private java.util.Map	loadRules(java.lang.String ruleset) Loads access rules by storing them in a hashmap.
private boolean	matchRule(java.util.Map map, java.lang.Class clazz, java.lang.String action) Checks to see if the current user has access to the specified Class and action.
private boolean	matchRule(java.util.Map map, java.lang.String path) Checks to see if the current user has access to the specified data, File, Object, etc.
private boolean	overlap(java.util.List ruleActions, java.lang.String action) This method merely checks to see if ruleActions contains the action requested.
private boolean	overlap(java.util.Set ruleRoles, java.util.Set userRoles) Return true if there is overlap between the two sets.
private FileBasedACRs.Rule	searchForRule(java.util.Map map, java.util.Set roles, java.lang.Class clazz, java.lang.String action) Search for rule.
private FileBasedACRs.Rule	searchForRule(java.util.Map map, java.util.Set roles, java.lang.String path) Search for rule.
private java.util.List	validateRoles(java.util.List roles) Checks that the roles passed in contain only letters, numbers, and underscores.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

urlMap

private java.util.Map urlMap

The url map.

functionMap

private java.util.Map functionMap

The function map.

dataMap

private java.util.Map dataMap

The data map.

fileMap

private java.util.Map fileMap

The file map.

serviceMap

private java.util.Map serviceMap

The service map.

deny

private FileBasedACRs.Rule deny

A rule containing "deny".

logger

private Logger logger

The logger.

Constructor Detail

FileBasedACRs

public FileBasedACRs()

Method Detail

isAuthorizedForURL

public boolean isAuthorizedForURL(java.lang.String url)

Check if URL is authorized.

Parameters:

url - The URL tested for authorization

Returns:

true if access is allowed, false otherwise.

isAuthorizedForFunction

public boolean isAuthorizedForFunction(java.lang.String functionName)
                                throws AccessControlException

TODO Javadoc

Throws:

AccessControlException

isAuthorizedForData

public boolean isAuthorizedForData(java.lang.String action,
                                   java.lang.Object data)
                            throws AccessControlException

TODO Javadoc

Throws:

AccessControlException

isAuthorizedForFile

public boolean isAuthorizedForFile(java.lang.String filepath)
                            throws AccessControlException

TODO Javadoc

Throws:

AccessControlException

isAuthorizedForService

public boolean isAuthorizedForService(java.lang.String serviceName)
                               throws AccessControlException

TODO Javadoc

Throws:

AccessControlException

matchRule

private boolean matchRule(java.util.Map map,
                          java.lang.String path)

Checks to see if the current user has access to the specified data, File, Object, etc. If the User has access, as specified by the map parameter, this method returns true. If the User does not have access or an exception is thrown, false is returned.

Parameters:

map - the map containing access rules

path - the path of the requested File, URL, Object, etc.

Returns:

true, if the user has access, false otherwise

matchRule

private boolean matchRule(java.util.Map map,
                          java.lang.Class clazz,
                          java.lang.String action)

Checks to see if the current user has access to the specified Class and action. If the User has access, as specified by the map parameter, this method returns true. If the User does not have access or an exception is thrown, false is returned.

Parameters:

map - the map containing access rules

clazz - the Class being requested for access

action - the action the User has asked to perform

Returns:

true, if the user has access, false otherwise

searchForRule

private FileBasedACRs.Rule searchForRule(java.util.Map map,
                                         java.util.Set roles,
                                         java.lang.String path)

Search for rule. Four mapping rules are used in order: - exact match, e.g. /access/login - longest path prefix match, beginning / and ending /*, e.g. /access/* or /* - extension match, beginning *., e.g. *.css - default servlet, specified by the single character pattern /

Parameters:

map - the map containing access rules

roles - the roles of the User being checked for access

path - the File, URL, Object, etc. being checked for access

Returns:

the rule stating whether to allow or deny access

searchForRule

private FileBasedACRs.Rule searchForRule(java.util.Map map,
                                         java.util.Set roles,
                                         java.lang.Class clazz,
                                         java.lang.String action)

Search for rule. Searches the specified access map to see if any of the roles specified have access to perform the specified action on the specified Class.

Parameters:

map - the map containing access rules

roles - the roles used to determine access level

clazz - the Class being requested for access

action - the action the User has asked to perform

Returns:

the rule that allows the specified roles access to perform the requested action on the specified Class, or null if access is not granted

overlap

private boolean overlap(java.util.Set ruleRoles,
                        java.util.Set userRoles)

Return true if there is overlap between the two sets. This method merely checks to see if ruleRoles contains any of the roles listed in userRoles.

Parameters:

ruleRoles - the rule roles

userRoles - the user roles

Returns:

true, if any roles exist in both Sets. False otherwise.

overlap

private boolean overlap(java.util.List ruleActions,
                        java.lang.String action)

This method merely checks to see if ruleActions contains the action requested.

Parameters:

ruleActions - actions listed for a rule

action - the action requested that will be searched for in ruleActions

Returns:

true, if any action exists in ruleActions. False otherwise.

validateRoles

private java.util.List validateRoles(java.util.List roles)

Checks that the roles passed in contain only letters, numbers, and underscores. Also checks that roles are no more than 10 characters long. If a role does not pass validation, it is not included in the list of roles returned by this method. A log warning is also generated for any invalid roles.

Parameters:

roles - roles to validate according to criteria started above

Returns:

a List of roles that are valid according to the criteria stated above.

loadRules

private java.util.Map loadRules(java.lang.String ruleset)

Loads access rules by storing them in a hashmap. This method begins reading the File specified by the ruleset parameter, ignoring any lines that begin with '#' characters as comments. Sections of the access rules file are split by the pipe character ('|'). The method loads all paths, replacing '\' characters with '/' for uniformity then loads the list of comma separated roles. The roles are validated to be sure they are within a length and character set, specified in the validateRoles(String) method. Then the permissions are stored for each item in the rules list. If the word "allow" appears on the line, the specified roles are granted access to the data - otherwise, they will be denied access. Each path may only appear once in the access rules file. Any entry, after the first, containing the same path will be logged and ignored.

Parameters:

ruleset - the name of the data that contains access rules

Returns:

a hash map containing the ruleset

loadDataRules

private java.util.Map loadDataRules(java.lang.String ruleset)

Loads access rules by storing them in a hashmap. This method begins reading the File specified by the ruleset parameter, ignoring any lines that begin with '#' characters as comments. Sections of the access rules file are split by the pipe character ('|'). The method then loads all Classes, loads the list of comma separated roles, then the list of comma separated actions. The roles are validated to be sure they are within a length and character set, specified in the validateRoles(String) method. Each path may only appear once in the access rules file. Any entry, after the first, containing the same path will be logged and ignored.

Parameters:

ruleset - the name of the data that contains access rules

Returns:

a hash map containing the ruleset

commaSplit

private java.util.List commaSplit(java.lang.String input)

This method splits a String by the ',' and returns the result as a List.

Parameters:

input - the String to split by ','

Returns:

a List where each entry was on either side of a ',' in the original String