HAProxy Enterprise Documentation 2.0r1

Implementing SSO

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:

  • <HAPEE_DIR>/sso/portal/logo.png (or logo.jpg)

  • <HAPEE_DIR>/sso/portal/css.css

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.

HAProxy Enterprise headers




An action that can be any of the following:

  • frm: display the authentication form to the user

  • fOK: display the login confirmation page: You now have access to application {%app%}

  • lOK: display the logout confirmation page: You have been logged out

  • dny: access denied

  • err: an error occurred


A message to display to the user


The domain


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.

X-SSO-LOGIN (SSO >= v1.2 or ALOHA >= 10.5.6)

If set_login option is set to 1, this header will contain the user login.

X-SSO-REDIR_QS (SSO >= v1.2 or ALOHA >= 10.5.6)

This header redirects users to the page they want to access before being redirected to the authentication portal.

  • If this header is set, the server must include its content into the form the user will POST.

  • For example, you can add a hidden field. This field must be called posted_redir.

X-SSO-REDIR_URL (SSO >= v1.2 or ALOHA >= 10.5.6)

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.

The POST action must be able to post on the same URL.

A minimal form could be the following:

<form method="POST">
  <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="..." />

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

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

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

      On Windows:

      ktpass /out myapp.keytab /mapuser <service-user>MYDOMAIN.NET /princ HTTP/myapp.mydonain.net@MYDOMAIN.NET /pass <PASSWORD>
  3. Update the keytab_file directive, if needed.

  4. Add the application to conf/sso.map.

  5. In the configuration file so.ini, add the application section and attach it to the correct domain.

  6. Add the specified backend to haproxy.cfg.

  7. 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-ACTION: alw

    • X-SSO-LOGIN: <user login> (SSO >= v1.2 or ALOHA >= 10.5.6)

Next up

Configuring SSO