The HAProxy 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 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


If you use Microsoft Active Directory, it becomes a central part of the SSO solution. Hence, you must set it up correctly for proper operation. See Active Directory documentation for information.

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.

Refer to the following documents for more information:

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

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

Setting up SSO

In ALOHA, you can either:

  • Use the template from the LB "Admin" tab.

  • Configure manually SSO, as follows:

    1. Refer to the section Configuring SSO

    2. Add backends for each of your applications.

    3. You can enable verbose debugging of the SSO agent, as follows:

      config set sso debug '--debug-all'
    4. Enable SSO:

      config set haproxy sso 1
      config sso set autostart 1
      service sso start
    5. Restart HAProxy:

      service haproxy restart