====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.

===Access Control Options===

Below is an example of the default security settings.

<code javascript>
{
	"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
	}
}
</code>

===Paths===

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.

===Groups===

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...

[[security_block|block]] - Denies all access \\
[[security_cert|cert]] - Requires a SSL/TLS client certificate \\
[[security_open|open]] - Allows access to anyone \\
[[security_isuser|isuser]] - Allows access to a specific user \\
[[security_token|token]] - Requires a specific HTTP header/token \\
[[security_userlevel|userlevel]] - Allows access to a specific user level \\
[[security_whitelist|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'.

===Combining Rules===

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

See the section on [[Combining Security Rules|combining rules]] for more details.

===Settings===

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

The following settings are available...

[[security_diagnostics|diagnostics]] - Enables diagnostic values in Access Denied errors \\
[[security_lockout|lockout]] - Locks all access to the ARDI server for all users \\

===Examples===

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

==local==

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**).//

==localnet==

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

==admin==

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.// 

==restricted==

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.//

==localadmin==

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.

===Modifying Rules===

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

The **[[security_terminal|terminal]]** option stops all processing and gives the user access to the resource.

The **[[security_demote|demote]]** option lowers the permission of the current user to prevent writing or other changes. 

The **[[security_elevate|elevate]]** option raises the permission of the current user to either the //editor// or //creator// level. 

**[[security_paramfilter|Parameter Filters]]** allow you to specify specific query parameters (or ranges of parameters) that are allowed.

Adding [[security_secure|secure]] ensures that the user is accessing the endpoint via SSL/TLS.

===Advanced Rules===

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