API authentication

From Halon, SMTP software for hosting providers
Jump to: navigation, search
The API functions and variables is documented in the HSL reference manual.

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. The most common applicability 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 clicking on the "API authentication script" button on the "Users" page.

Examples

LDAP example

This example can be used for authentication against an LDAP directory service. Start with adding a LDAP source in your configuration under the LDAP sources page. Once you've added a LDAP source you'll need to edit the script, replace "company.local", adjust the CN in the query, and make sure you add the LDAP source. In this example the LDAP source is named "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]
 ]);

If you want to make use of nested groups you can use a query that looks something like this:

"query" => "(&(samAccountName=%s)(memberOf:1.2.840.113556.1.4.1941:=CN=Halon Mail Gateway Admins,CN=Users,DC=company,DC=local))" 

For more information about this OID, see the following link.

TACACS+ example

In order to authenticate against a TACACS+ server (without access levels). Use the following example.

$hostopt = [
   
"host" => "10.0.0.31",
   
"secret" => "mysharedsecret",
   
"clientip" => $clientip
  
];
if (
tacplus_authen($hostopt$username$password) == 1) {
  
Authenticate();

If you need to verify access levels. tacplus_author() provides the means to do so. In order to debug tacplus authentication use the "System -> Script sandbox" in the web UI and print the result of $ret. You must however set the variables $clientip, $username and $password, like the authentication context would.

$hostopt = [
   
"host" => "10.0.0.31",
   
"secret" => "mysharedsecret",
   
"clientip" => $clientip
  
];
if (
tacplus_authen($hostopt$username$password) == 1) {
 
$ret tacplus_author($hostopt$username, ["service=admin"]);
 if (
is_array($ret) and in_array("halon=test"$ret)) {
  
Authenticate();
 }

Custom permissions

It's possible to delegate certain rights to API users. This script does not allow the user to change any of the configuration settings on the Halon but the user is still allowed to delete, bounce, release and preview mail as well as clear rate limits.

if ($username == "username" and $password == "changethis") {
    if (
$soapcall == "mailQueueDelete"Authenticate();
    if (
$soapcall == "mailQueueRetry"Authenticate();
    if (
$soapcall == "mailQueueBounce"Authenticate();
    if (
$soapcall == "hslRateClear"Authenticate();
    if (
$soapcall == "commandRun" and
        
$soapargs["argv"][0] == "previewmessage")
            
Authenticate();
    
Authenticate(["accesslevel" => "r"]);

You can also add permissions for editing a specific virtual text file by including the following lines in your SOAP calls

if ($soapcall == "configKeySet" and 
    
$soapargs["key"] == "file__X")
        
Authenticate(); 

where "file__X" is the file that you want the user to be able to edit.

It's also possible to specifically deny a user from doing certain things, the following lines denies the user from previewing or downloading email from the queue.

if ($soapcall == "commandRun" and
    
$soapargs["argv"][0] == "previewmessage")
        
Deny();
if (
$soapcall == "fileRead" and
    
substr($soapargs["file"], 024) == "/storage/mail/processed/")
        
Deny(); 

Cisco ACS configuration

Cisco ACS devices (clients) list

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

Cisco ASC as well as Halon SMTP software 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.

TACACS+

You may pass AV-pairs back and forth over the TACACS+ protocol, in order to set different access levels etc.

tac_plus (TACACS+ server)

tac_plus[1] is freely available TACACS+ server (eg. apt-get install tacacs+). This example provides a simple configuration to authenticate users with group permissions.

/etc/tacacs+/tac_plus.conf

accounting file = /var/log/tac_plus.acct

key = testing123

group = sp-admin {
        service = sp-admin {
                halon = rw-admin
        }
}

user = larry {
        member = sp-admin
        login = des eC1KaWssL2i2c # (1) generated with tac_pwd
}

$hostopt = [
   
"host" => "10.0.0.1",
   
"secret" => "testing123",
   
"clientip" => $clientip
  
];
if (
tacplus_authen($hostopt$username$password) == 1) {
 
$ret tacplus_author($hostopt$username, ["service=sp-admin"]);
 if (
is_array($ret) and in_array("halon=rw-admin"$ret)) {
  
Authenticate();
 }