Difference between revisions of "API authentication"

From Halon, SMTP software for hosting providers
Jump to: navigation, search
(LDAP example)
Line 14: Line 14:
 
=== LDAP example ===
 
=== 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 (<tt>ldap__X</tt> configuration key, in this example, shortcut "ldap:1").  
 
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 (<tt>ldap__X</tt> configuration key, in this example, shortcut "ldap:1").  
<hsl>
+
<hsl type="api">
 
$r = ldap_search("ldap:1", $username,
 
$r = ldap_search("ldap:1", $username,
 
   [
 
   [

Revision as of 13:38, 19 February 2016

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

Architecture

The main interface of a Halon 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.

This script is executed for every SOAP call, if you use any external authentication source (eg. LDAP, TACACS+ or RADIUS) and do not need different permission per user for each SOAP function, it's highly recommended to implement the cache [] before each external lookup.

If someone tries to authenticate (sign in) with a username/password combination that is not correct according to the built-in user configuration list, the system authentication script is executed.

Functions & variables

Functions and the predefined variables available in the system authentication extension is documented at HSL API

Examples

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]
 ]);

You can limit what a certain group of LDAP users can do when they have logged in. 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:

$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)) {
      if (
$soapcall == "mailQueueDelete"Authenticate();
      if (
$soapcall == "mailQueueRetry"Authenticate();
      if (
$soapcall == "mailQueueBounce"Authenticate();
      if (
$soapcall == "commandRun" and
          
$soapargs["argv"][0] == "previewmessage")
              
Authenticate();
      
Authenticate(["accesslevel" => "r"]);

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 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();
 }

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

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();
 }