Single sign-on (SSO) is a property of access control of multiple related, yet independent, software systems. With this property, a user logs in with a single ID and password to gain access to a connected system or systems without using different usernames or passwords, or in some configurations seamlessly sign on at each system.

This HAProxy SSO solution allows you to implement SSO on a Microsoft Active Directory domain.

It is composed of a set of configuration files, and a program called spoa-sso, which talks to HAProxy 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 Kerberos

  • 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


Since Active Directory is a central part of the SSO solution, it must be set up for correct operation. See Active Directory documentation for information.

The following sections define the SSO-managed applications that belong to one or several domains.

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:

    rdns = false

Kerberos protocol

Kerberos is a computer network authentication protocol that works on the basis of tickets to allow nodes to communicate over a non-secure network and to prove their identity to one another in a secure manner.

This SSO solution implements several modes of operation for the Kerberos protocol.

It implements the s4u (services for user) extensions from Microsoft that allow enhanced security and user impersonation.

Refer to the following documents for more information:

[MS-SFU]: Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol

The s4u is the recommanded mode and should be used when possible.

HAProxy, SPOE protocol, and SSO agent

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

It requires HAProxy 1.7r2 or greater or 1.8 or greater. The SSO agent is independent from HAProxy 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

Single Sign On flowchart 1 Single Sign On flowchart 2


The Haproxy 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:

$ sudo apt install hapee-extras-spoa-sso

Process Management

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>

Command line options

The following options are available on 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
   --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:
   -P <port>              Specify the port to listen on (default : 12345)
   -n <num-workers>       Specify the number of workers (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)


The following limitations apply:

  • SPNEGO/negotiate only

  • Active Directory only

  • May require 16k buffer size, since the www-authentication and authorization headers can be long.