HSL System Authentication
The system authentication extension to the HSL scripting language provides the ability to authenticate system users (administrators) using more advanced methods than the built-in user configuration list (system_user__X configuration key) found on the Users tab of the Administration section as seen in the figure to the right.
The most common application of this extension is to do external authentication against a LDAP, TACACS+ or RADIUS server. Please note that most of these functions, such as tacplus_authen(), are part of the core functions, and naturally documented on that page. The script is configured by pressing the Fullscreen Editor button. Please note that the Close button in the fullscreen editor doesn't save the script; you have to press the Save button.
Contents |
Architecture
The interface of H/OS (the operating system) is a SOAP API, which is used by the web administration, console interface, programming interface for integrators, etc. This API is protected by authentication, which normally equals to the configured users. Permission flags such as "r" (for read-only) limit the set of SOAP functions that are accessible by a user.
If someone tries to authenticate (sign in) with a username/password combination that is not correct according to the user configuration (system_user__X configuration key), the system authentication script is executed. The script (system_authentication_script configuration key) is found on the the Users tab of the Administration section. The variables available in the system authentication extension are
| Name | Example | Description |
|---|---|---|
| $username | "admin" | The username that is provided by the authenticating client |
| $password | "secret" | The password that is provided by the authenticating client |
| $service | "webui" | webui, quarantine or console |
| $clientip | "192.168.0.10" | The IP address of the authenticating client |
| $soapcall | "System-GetKey" | The SOAP API command that the client tries to execute |
Functions
As noted above, most of the relevant functions for external authentication is are core functions. The functions that are explicitly tied to the system authentication script are listed below.
Authenticate($options)
This is a final action that accepts the authentication request (allowing access to the system and it's SOAP API) and terminates execution. $options is an optional associative array with parameters for the successful authentication:
| Name | Default | Example | Description |
|---|---|---|---|
| fullname | "Script User" | "TACACS+ User" | Corresponds to the "Full Name" property of configuration users |
| accesslevel | "" | "r" | The access level string, such as "r" for read-only |
Deny()
This is a final action that terminates the execution of the script, and denies the authentication request (triggering a "wrong username or password" error).
Examples
Although this scripting context allows for all imaginable applications, the most common scenario is to enable authentication against an external service such as a directory service (like Microsoft's Active Directory) or an access system (like Cisco ACS).
LDAP example
For authentication against a LDAP directory service, this example can be used as a starting point. Replace "company", "local", adjust the CN in the query, and make sure that you have an LDAP server object (ldap__X configuration key, in this example, shortcut "ldap:1").
$r = ldap_search("ldap:1", $username,
[
"username"=>"$username@company.local",
"password"=>$password,
"query"=>"(&(samAccountName=%s)(memberOf=CN=Halon Mail Gateway Admins,CN=Users,DC=company,DC=local))"
]);
if (is_array($r) and count($r))
{
Authenticate([
"fullname"=>$r[0]["displayName"][0]
]);
}
Cisco ACS configuration
Cisco Secure Access Control Server (ACS) is an "access policy control platform", or plainly speaking a Network Access Control (NAC) server. It allows centralized access control management in larger enterprises. This section is not intended to be a complete setup guide for such a system, rather provide you with some hints on how you may interact with the H/OS 2 platform.
Cisco ASC as well as Halon VSP/SPG supports both Radius and TACACS+ authentication and authorization, none of which we recommend over the other.
RADIUS
In order to pass values back and forth over the RADIUS protocol, you must define a vendor specific id/type. Halon Security's vendor ID is 33234. You may use any attribute ID, the only requirement is that the type must be set to string.
Adding a vendor ID for Halon
Adding a string for H/OS access level
Using the vendor string on a network access profile (read-only access)
Creating an authorization policy with the access profile
TACACS+
You may pass AV-pairs back and forth over the TACACS+ protocol, in order to set different access levels etc.
Adding a shell profile for read-only access
Creating an authorization policy with the shell profile
