HAProxy Enterprise Documentation 2.5r1

Active Directory

The HAProxy Enterprise Single Sign-On solution allows you to set up SSO on a Microsoft Active Directory domain.

It can optionally use the Kerberos protocol for authentication. It is also compatible with Microsoft Active Directory or OpenLDAP servers.

It is composed of a set of configuration files, and a program called spoa-sso, which talks to HAProxy Enterprise using the SPOE (Stream Processing Offload Engine) protocol.

SSO allows you to:

  • Implement access control to applications on your network, even if the applications themselves do not support authentication or the Kerberos protocol.

  • Implement access control and identity delegation to your internal applications, from an external network or from a VPN.

  • Provide Single Sign On ability in a Microsoft Active Directory Domain.

Terms Used

The SSO solution allows users to access different resources and applications, depending on their rights.

  • In a Microsoft environment, users of an organization are part of a domain.

  • Active Directory is a set of services that provide authentication, identification, and management of users of a domain.

Active Directory also deals with these protocols within the domain:

  • DNS

  • LDAP

  • Kerberos

Kerberos protocol

This SSO solution optionally implements the S4U (services for user) extensions from Microsoft that allow enhanced security and user impersonation.

It supports SPNEGO negotiation mechanism.

See also

DNS Protocol

To use successfully the Kerberos protocol, you must observe some requirements regarding the DNS configuration:

  • The server running the SSO agent must have a proper hostname that can be resolved to an IP, using DNS.

  • You can also modify your /etc/hosts file

  • The IP address of the Kerberos KDC is retrieved via DNS, using "_kerberos" service.

  • If you cannot configure your DNS server, you must specify the KDC in /etc/krb5.conf.

  • The reverse DNS must also work. If not, you must add /etc/krb.conf to disable the reverse DNS:

    [libdefaults]

rdns = false

HAProxy, SPOE protocol, and SSO agent

The SSO agent uses HAProxy's Stream Processing Offload Engine protocol (SPOA).

It requires HAProxy Enterprise 1.7r2 or greater or 1.8 or greater. The SSO agent is independent from HAProxy Enterprise and runs as a separate process.

Each HTTP request and response is passed to the SSO agent which checks if the user is allowed to access the requested resource and determines whether to:

  • Allow

  • Deny

  • Present the authentication form

Life of a request:

Single Sign On flowchart 1

Life of a response:

Single Sign On flowchart 2

Installing HAProxy Enterprise SPOA SSO

The HAProxy Enterprise SPOA SSO service is distributed as a package for all Linux distributions that support HAProxy Enterprise.

If you use a Debian based system, type the following command to install the solution:

$ # On Debian/Ubuntu
$ sudo apt-get install hapee-extras-spoa-sso
$ # On CentOS/RedHat/Oracle/Photon OS
$ sudo yum install hapee-extras-spoa-sso
$ # On SUSE
$ sudo zypper install hapee-extras-spoa-sso
$ # On FreeBSD
$ sudo pkg install hapee-extras-spoa-sso

Managing the HAProxy Enterprise Process

You can control the spoa_sso process using the following System V init script as follows:

$ sudo service hapee-extras-spoa-sso <start|stop|status|check|restart|condrestart|tryrestart|forcereload|help>

Setting up SSO

The following options to set up SSO are available in the command line:

Usage : ./spoa-sso [OPTION]...
   -h                     Print this message
   --debug-spoe -d        Debug SPOE
   --debug-spoe-variables Debug SPOE variables
   --debug-sso            Debug SSO actions
   --debug-ldap           Debug LDAP
   --debug-krb            Debug Kerberos
   --debug-all
   --print-cfg            Display configuration during startup
   --check-cfg -c         Check configuration then exit
   --gid                  run in the specified group
   --uid                  run as the specified user
   -F                     disables syslog output, and stay in foreground
   -s                     Use syslog
   -p <pidfile>           Write the server PID into the specified file
   -A <address>           Listen on this address (default: 127.0.0.1)
   -P <port>              Specify the port to listen on (default : 12345)
   -n <num-workers>       Specify the number of workers (default : 10)
   -b <conn-backlog>      Specify the connection backlog value (default : 10)
   -N                     Do not verify SSL certificates with LDAP (LDAPTLS_REQCERT=never)
   -f config_file         .INI file containing the SSO configuration
                          (default: sso.ini)

Next up

Implementing SSO