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.
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:
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:
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
The reverse DNS must also work. If not, you must add
/etc/krb.confto disable the reverse DNS:
[libdefaults] rdns =
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:
Present the authentication form
Setting up SSO
In HAProxy ALOHA, you can either:
Use the template from the LB "Admin" tab.
Configure manually SSO, as follows:
Refer to the section Configure SSO
Add backends for each of your applications.
You can enable verbose debugging of the SSO agent, as follows:
config set sso debug '--debug-all'
config set haproxy sso 1 config sso set autostart 1 service sso start
$ service haproxy restart
Using the provided built-in Web portal
If you use the default built-in Web portal, you can customize your company logo and your CSS file.
The location of these files is:
Implementing a custom Web portal
To implement a Web portal that displays a login form to the user, you only need a simple Web server that handles HTTP headers sent by HAProxy.
An action that can be any of the following:
A message to display to the user
The application that the user wants to access. It is determined by the URL and the SSO agent.
The main URL of the application. The web server can include a link to this page to lead the user directly to the application.
This header redirects users to the page they want to access before being redirected to the authentication portal.
Contains the URL that users want to access. You can redirect them to this URL after a successful authentication.
Establish an authentication form
This HTML page must contain an HTML form to allow the user to enter his login and password and to select the domain to log on.
POST action must be able to post on the same URL.
A minimal form could be the following:
<input name= "login" />
<input name= "password" />
<select name= "domain">
<option value= "mydomain.net">My Domain</option>
<!-- optional field. It should contain the value extracted from the
X-SSO-REDIR_QS header -->
<input type= "hidden" name= "posted_redir" values= "..." />
POST is done on the form backend and handled by HAProxy, which extracts the information and passes it on to the SSO agent.
Add SSO ability to an application
After you set up SSO, use the following procedure to add more applications:
Add a new domain:
You must add the new domain in a Web form of an HTML page. The user must be able to select it, and you must include its value in the POST.
To add an application if you use Kerberos with an Active Directory:
Add a new service user associated with the service principal name (SPN) of your application.
Create a new Keytab for the new SPN or add it to an existing Keytab.
ktpass /out myapp.keytab /mapuser <service-user>MYDOMAIN.NET /princ HTTP/myapp.mydonain.net@MYDOMAIN.NET /pass <PASSWORD>
keytab_filedirective, if needed.
Add the application to
In the configuration file
so.ini, add the application section and attach it to the correct domain.
Add the specified backend to
To check if a user is allowed to access an application, you must check that the
X-SSO-*headers are as follows:
X-SSO-APP: <name of the application>
X-SSO-DOMAIN: <name of the domain>
X-SSO-LOGIN: <user login> (SSO >= v1.2 or ALOHA >= 10.5.6)
The single sign-on (SSO) function requires several configuration files.
On HAProxy ALOHA, you can use the templates that HAProxy ALOHA provides to generate automatically your configuration.
Below is an explanation of each configuration file.
haproxy-sso.cfg defines the main HTTP frontend that HTTP clients require in order to use SSO.
It also defines the HTTP rules, ACLs, and checks involved between the SPOE agent and HAProxy.
You may have to modify parts of this file depending on your Active Directory setup and your network configuration.
The bind directive of the frontend:
If you use your own external Web server to host the SSO portal, use:
backend sso_portal # this is the webserver used to diplay the SSO login form mode http server sso_portal-1 my_web_server:80
If you want to use the built-in LUA Web server, use:
sso_portal.lua# ... backend sso_portal mode http http-request use-service lua.sso_portal
Configure SSO SPOE
haproxy-sso-spoe.cfg file contains information regarding which messages to exchange between the SSO SPOE daemon and HAProxy.
We recommend that you do not modify it and keep it as provided.
Specify SSO mappings
sso.map must contain the mappings between your different applications and the
# Host header <domain>/<app>
Configure the SSO daemon
sso.ini file is the main configuration file of the SSO daemon. It must contain information about each application that you want to manage.
It uses a similar syntax to any typical Windows
Lines starting with
Comments can appear at the end of any line when preceded by a space.
There are several sections in
The default section (
[defaults]) contains default values. These values are inherited by each domain.
Domain sections (
[domain:mydomain]) define properties valid for the scope of the entire domain.
Other sections are applications sections.
At least one domain section is required, and each application must be attached to exactly one domain. Applications inherit the properties of their domain, and can also override them.
Some properties can include keywords within brackets such as
<KRB_REALM>that get replaced with appropriate values at run time. For example, if you prefer that all your backends start with
bk_, you can use:
backend = bk_<APP_NAME>
Each application must have a unique name. To name applications, you may use alphanumeric characters or underscores. This name must match a name in the
The internal host name of your application. It must match the domain part of the Kerberos SPN (ie HTTP/mydomain.int)
The external FQDN of your application.
When setting this field to
Allows you to choose the location of the Kerberos tickets cache:
Defines the domain attribute that the SSO agent must use when setting its cookie. You must match the longest common part of your external host name.
Defines the lifetime of the SSO cookie (in seconds). Past this time, the user must reauthenticate. Default:
For each domain, you must define additional LDAP and Kerberos parameters as follows:
Controls whether to use TLS when connecting to the LDAP server:
Must be defined for each application.
Indicates the URLs to reach the login. When users must enter their credentials, HAProxy redirects them here.
An authenticated user who reaches this URL gets logged out.
After a successful authentication, a message displays with a link to access the application.
Secret used to encode the current user URL, and to redirect the user after a successful authentication.
Use this directive to restrict access to a particular application to a specified group of users.
By default, all applications require the user to log into the corresponding domain and a valid cookie to grant access.
If set to
LDAP member to search for when computing LDAP groups membership (default:
LDAP filter to apply when computing LDAP groups membership (default:
Diagnostics and troubleshooting
LDAP and Kerberos issues
The SSO solution does not require the file
/etc/krb5.conf, but you can use it if the file is present in order to override default values or define a specific set of ciphers.
Refer to the MIT Kerberos documentation for more information.
To troubleshoot your environment, you can perform the following tasks:
Set the environment variable KRB5_TRACE to a log file, or to
/dev/stdoutto get more verbose Kerberos diagnostics. In addition, you can pass the
--debug-krbflag to the SSO daemon.
Use the provided tool called
sso-diagto test parts of the workflows involved when working with Kerberos.
Test ticket creation in Kerberos using:
./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -u USER -p PASSWORD krb_ticket
Check that your access rules or required LDAP groups are set and configured correctly by launching:
./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -u USER -p PASS authand replacing
PASSwith appropriate values. This directive simulates a user doing a POST on the authentication form with the supplied credentials.
You can also use
./sso-diag -f sso.ini -a MYAPP -d MYDOMAIN -A MYAPP2 -D MYDOMAIN2 -u USER -p PASS checkto simulate a POST with the supplied credentials on
MYDOMAIN, and then try to access
Get the status of the different worker threads running on the SSO agent by sending a SIGUSR1 at any time (when launched with
HAProxy 503 error
If you get a 503 error (service unavailable) coming from HAProxy, launch the agent with the
If the SSO application granted access to the URL, check that your backend is correctly configured in
For example, if you get any of the following messages, check that the POC backend exists in the file
Encode SPOE set-var str scope=1 sso_app=poc Encode SPOE set-var str scope=1 sso_domain=poc Encode SPOE set-var str scope=1 action=alw Encode SPOE set-var str scope=2 backend=poc
Message: Invalid domain xxx: 'cannot match config'
This means that the domain, which was set using
sso.mapby matching the host header, has no corresponding section in
- Message: 'No authentication info found' displays repeatedly while
logging on the form
If you get this error, check the
sso_cookie_domainmust match the domain of your applications.
When logging in with correct credentials, you should see a response header similar to this:
Set-Cookie: sso-cookie=abc122342; domain=mydomain.net
No server contact error
Message: 'Cannot contact server' or 'error in
Check that you configured your DNS correctly, and that you can reach the LDAP server on the correct port (standard ports are 636 or 389 depending on the configuration).
Failure to connect with LDAP server
Message: 'TLS or SSL already in effect'
You cannot use a
ldaps://URL and a
1at the same time. They are mutually exclusive.
Message: 'GnuTLS: A TLS packet with unexpected length was received'
You may get this error on servers where an old version of the GnuTLS or OpenSSL library was installed.
You can change the ciphers used by LDAP libraries with environment variables. For instance:
SSL certificate error
- Message: SSL routines
ssl3_get_server_certificate:certificate verify failed (unable to get local issuer certificate)
You can bypass the LDAP certificates verification by using the
This sets the environment variable
name not found'
The host name of the server running the SSO agent must resolve to an IP.
Add it to your DNS server or in your
Reverse DNS must work on the server running the SSO agent.
You must be able to resolve your server IP to its host name.
If not, you can add this
/etc/krb.conf, to disable the reverse DNS:
[libdefaults] rdns =