Access Control

Apart from basic user account access control built into ARDI, and methods available using Apache modules, you can also setup access control to specific endpoints (for example, particular web pages).

You can do this through the security files. There's one shared file at /model/defaults in your ARDI installation directory, and you can also create site-specific security files by creating a file called security.rules in your site folder.

Note that these files are not additive. If you use a site-specific security file, the rules in the default file will be ignored. As such, we suggest copying the existing file as a getting-started point.

Because this security layer is in addition to the built-in user security of ARDI, security rules are designed to allow access by default.

Below is an example of the default security settings.

{
	"paths": {
		"api/drivers": "local",
		"api/driverdata": "local",
		"api/driverdetails": "local",		
		"admin/": "admin",
		"admin/sites/purge": "localadmin",
		"admin/sites/reset": "localadmin",
		"admin/restore/": "restricted"
	},
	"groups": {
		"local": {
			"type": "whitelist",
			"list": ["127.0.0.1","localhost"]
		},	
		"localnet": {
			"type": "whitelist",
			"list": ["192.168.0.1-255","127.0.0.1"]
		},	
		"admin": {
			"type": "userlevel",
			"level": "admin"
		},
		"blocked": {
			"type": "block"
		},
		"restricted": [[{
				"type": "isuser",
				"list": ["admin"]
			}],[{
				"type": "whitelist",
				"list": ["127.0.0.1"]
		}]],
		"localadmin": [ {
				"type": "isuser",
				"list": ["admin"]
			},
			{
				"type": "whitelist",
				"list": ["127.0.0.1"]
			}]
	},
	"settings": {
		"diagnostics": true,
		"lockout": false
	}
}

The paths section contains a list of web URLs that you'd like to protect.

A url that ends with a slash (/) character protects the entire folder, while one that ends without a slash only protects that specific URL.

For example, admin/sites/purge specifically protects the page that allows you to erase your ARDI database, while admin/ protects every page in your 'admin' folder.

Each path is linked to the name of a group. This group defines the access control rules.

Access control rules are bundled into groups, making it easier to modify security settings (for example, it's much easier to update one group than it is to update a dozen individual paths).

Each group has a either a single security rule, or a list of them. Each security rule has a type, such as those below…

block - Denies all access
cert - Requires a SSL/TLS client certificate
open - Allows access to anyone
isuser - Allows access to a specific user
token - Requires a specific HTTP header/token
userlevel - Allows access to a specific user level
whitelist - Allows access to specific IP addresses

Many rules (such as whitelist, userlevel and isuser) can be set to deny rather than allow, making the 'whitelist' function work as a 'blacklist'.

Rules can be combined using arrays. Using these, it's possible to create logic within your rules.

See the section on combining rules for more details.

The 'settings' section allows you to adjust overall options for the security system.

The following settings are available…

diagnostics - Enables diagnostic values in Access Denied errors
lockout - Locks all access to the ARDI server for all users

Here we'll describe some of the groups that appear in the example above.

Only accessible from the ARDI server itself.

In the example, this is used to restrict the API functions for ARDI-to-driver communication (api/drivers, api/driverdata and api/driverdetails).

Restrict to the local machine and those computers on the local subnet

Restrict to only users in the 'admin' group.

The entire admin folder is protected against access by non-admin users. Note that most administrative pages have their own internal security tests that can't be overridden by this file.

These resources can only be accessed by someone who is the 'admin' user (not an adminstrator user, but the specific user called 'admin'), or by someone logged into the local system.

In this example, this is used to protect particularly destructive admin-only functions, such as erasing or replacing the database.

Similar to the rule above, but using an and rather than an or condition - these resources can only be the user called 'admin' who is also logged into the local system.

You can also use options to change how resources are accessed or how rules are processed.

The terminal option stops all processing and gives the user access to the resource.

The demote option lowers the permission of the current user to prevent writing or other changes.

The elevate option raises the permission of the current user to either the editor or creator level.

Parameter Filters allow you to specify specific query parameters (or ranges of parameters) that are allowed.

Adding secure ensures that the user is accessing the endpoint via SSL/TLS.

See the section on rule priority for more details on how rules are applied and can be prioritised.