Single sign-on (SAML)

HAProxy Enterprise’s Security Assertion Markup Language (SAML) module acts as a SAML Service Provider, providing single-sign-on (SSO) to any web application located behind an HAProxy Enterprise server.

This section provides an overview of the SAML module.

About SAML 2.0 and the module Jump to heading #

The XML-based Security Assertion Markup Language (SAML) 2.0 open-standard transfers identity data (assertions) between an Identity Provider (IdP) and a Service Provider (SP).

The SAML module acts as a SAML Service Provider. It provides Service Provider-initiated, cross-domain, web-based single-sign-on (SSO) to any web application located behind the load balancer. You then don’t have to implement SAML directly in your application.

It works like this:

1. A user visits a web application at its load balanced IP address.
2. The SAML module creates an Authentication Request (AuthnRequest) and redirects the user’s browser to the IdP (for example, to Microsoft Entra ID).
3. The user signs in via the IdP’s login page, and the IdP validates the credentials. Then the IdP redirects the user back to the load balancer.
4. The SAML module verifies the SAML response from the IdP and then allows the user to proceed to the web application. An HTTP cookie ensures that the user will not need to log in again during their session.

Features:

• Implement SSO seamlessly, even for legacy web applications.
• Configure logging and grant access using ACLs.
• Check SAML assertions or attributes with XPath (via the saml.ini file).
• Retrieve SAML assertions and use them as variables in your load balancer configuration. For example, you can then enhance logs and pass user information to the application via HTTP headers.

Configure the Identity Provider Jump to heading #

The Identity Provider (IdP) manages the user accounts and passwords, provides a login page, and validates credentials. The SAML module relies on you using a third-party IdP. In this section, we’ll describe how to set this up.

Use Microsoft Entra ID Jump to heading #

This section describes how to configure Microsoft Entra ID (formerly Azure Active Directory) as the IdP.

1. Sign in to the Azure portal.

2. Search for and select Microsoft Entra ID. If you manage multiple tenants, then choose Manage tenants, select the tenant with which you would like to enable single sign-on, and click Switch.

3. From the Microsoft Entra ID Overview page, add a new Enterprise application.

4. On the Browse Microsoft Entra Gallery screen, click Create your own application.

   • Give the app a name, such as samlapp.
   • Choose Integrate any other application you don’t find in the gallery (Non-gallery).
   • Then click Create.

   

5. Click Assign users and groups. Choose users and groups that should get sign-on access to your application. Then return to the Overview screen.

6. Click Set up single sign on, then choose SAML.

   The Set up Single Sign-On with SAML page opens. Edit the Basic SAML Configuration:

   Field	Description
   Identifier (Entity ID)	Choose a unique identifier for your application, such as samlapp.
   Reply URL (Assertion Consumer Service URL)	Set the URL at which HAProxy Enterprise will receive the SAML authentication token. For example, https://example.com/saml/reply.
   Logout URL	Set the URL at which HAProxy Enterprise will receive a logout message from Microsoft Entra ID. For example, https://example.com/saml/logout.

   Save and then close the basic SAML configuration panel.

7. Still on the Set up Single Sign-On with SAML page, edit the SAML Certificates.

   • For the Signing option choose Sign SAML response and assertion and set Signing Algorithm to SHA-256.
   • Save and close the SAML Signing Certificate panel.

8. You will need several properties of your Microsoft Entra ID enterprise application later when you configure HAProxy Enterprise. Save the following property values:

   Property	Where to find it
   Name	On the enterprise application’s Overview page.
   Application ID	On the enterprise application’s Overview page.
   Tenant ID	On the Microsoft Entra ID Overview page.

Configure the SAML module Jump to heading #

This section describes how to configure the SAML module on the load balancer.

1. On your HAProxy Enterprise load balancer, install the hapee-<VERSION>-lb-saml-sso package via your system’s package manager:

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-3.0r1-lb-saml-sso

   nix
   sudo apt-get install hapee-3.0r1-lb-saml-sso

   nix
   sudo yum install hapee-3.0r1-lb-saml-sso

   nix
   sudo yum install hapee-3.0r1-lb-saml-sso

   nix
   sudo zypper install hapee-3.0r1-lb-saml-sso

   nix
   sudo zypper install hapee-3.0r1-lb-saml-sso

   nix
   sudo pkg install hapee-3.0r1-lb-saml-sso

   nix
   sudo pkg install hapee-3.0r1-lb-saml-sso

2. This creates the folder /etc/hapee-<VERSION>/saml_examples. For Azure, copy the files from the saml_examples/azure to the parent directory, /etc/hapee-<VERSION>/. The files include:

   • authn_request.xml
   • logout_request.xml
   • saml.ini

3. Edit the copied file saml.ini. At the top of the file, change the values of the following fields to match your Microsoft Entra ID enterprise application’s properties:

   Property	Set it to
   {{ID_APP_NAME}}	Your Microsoft Entra ID enterprise application’s Name, from the enterprise application’s Overview page.
   {{IDP_APP_ID}}	Your Microsoft Entra ID enterprise application’s Application ID, from the enterprise application’s Overview page.
   {{IDP_TENANT_ID}}	Your Microsoft Entra ID Tenant ID, from the Microsoft Entra ID Overview page.
   {{APP_FQDN}}	The fully qualified domain name where HAProxy Enterprise listens for requests, such as example.com. This should match the FQDN you used when setting the Reply URL and Logout URL in Azure. Be sure to add this record in your DNS server so that users can access your application at this domain. Note that if this uses HTTPS, then you should configure your bind line in the load balancer configuration to also listen on HTTPS.

   An example portion of the saml.ini configuration:

   saml.ini
   ini
   [MySAMLApp]
   {{ID_APP_NAME}} = samlapp
   {{IDP_APP_ID}} = 0fbb284d-39ea-4fc6-9639-114b46b8dcb3
   {{IDP_TENANT_ID}} = abcdefg-1234-5678-abcd-efgh12345678
   {{CLAIM_PREFIX}} = http://schemas.xmlsoap.org/ws/2005/05/identity/claims
   {{APP_FQDN}} = example.com
   {{APP_LOGIN_URL}} = https://{{APP_FQDN}}/saml/reply
   {{APP_LOGOUT_URL}} = https://{{APP_FQDN}}/saml/logout
   {{APP_BACKEND}} = bk-{{APP_NAME}}                      
   

   saml.ini
   ini
   [MySAMLApp]
   {{ID_APP_NAME}} = samlapp
   {{IDP_APP_ID}} = 0fbb284d-39ea-4fc6-9639-114b46b8dcb3
   {{IDP_TENANT_ID}} = abcdefg-1234-5678-abcd-efgh12345678
   {{CLAIM_PREFIX}} = http://schemas.xmlsoap.org/ws/2005/05/identity/claims
   {{APP_FQDN}} = example.com
   {{APP_LOGIN_URL}} = https://{{APP_FQDN}}/saml/reply
   {{APP_LOGOUT_URL}} = https://{{APP_FQDN}}/saml/logout
   {{APP_BACKEND}} = bk-{{APP_NAME}}                      
   

   Running multiple applications

   Although the configuration in saml.ini defines only one SAML app named MySAMLApp, you can define multiple single sign-on apps. Copy all lines, except for the config_version line, and paste them below the existing lines, but replace MySAMLApp with a new name such as App2. Then change the properties to match your second application.

4. Also in the saml.ini file, add the following lines, changing mysecret to be your own, secret string. The module will use this to encrypt the sign-on cookie. If you ever need to change the secret, then store the new secret in saml_secret_2 and set current_saml_secret to 2.

   saml.ini
   ini
   saml_secret_1 = mysecret
   current_saml_secret = 1

   saml.ini
   ini
   saml_secret_1 = mysecret
   current_saml_secret = 1

5. Edit the HAProxy Enterprise configuration file, /etc/hapee-3.0/hapee-lb.cfg.

   • In the global section of your configuration, add the following lines. The saml-sso-load directive takes two arguments. The first is the path to the directory where you’ve stored the authn_request.xml and logout_request.xml files. The second is the path to your saml.ini file.

     hapee-lb.cfg
     haproxy
     global
       module-path /opt/hapee-3.0/modules
       module-load hapee-lb-saml-sso.so
       saml-sso-load /etc/hapee-2.9 /etc/hapee-2.9/saml.ini

     hapee-lb.cfg
     haproxy
     global
       module-path /opt/hapee-3.0/modules
       module-load hapee-lb-saml-sso.so
       saml-sso-load /etc/hapee-2.9 /etc/hapee-2.9/saml.ini

   • Copy the SAML section below into the frontend section for your load balanced application. Change the arguments given to the http-request saml-sso and http-response saml-sso directives to match the app name in saml.ini (for example, MySAMLApp). Also change the if statement to use your fully qualified domain name.

     Below, we add the directives to enable SAML single sign-on in the frontend:

     hapee-lb.cfg
     haproxy
     frontend fe_main
       bind :80
       bind :443 ssl crt /etc/hapee-3.0/ssl/cert.pem
       mode http
       option http-buffer-request
       tcp-request inspect-delay 5s
       
       # --------------------
       # ----SAML section----
       # --------------------
       http-request saml-sso MySAMLApp if { hdr(host) -i example.com }
       http-response saml-sso MySAMLApp
       default_backend bk-err
       use_backend %[var(txn.saml.saml_app_backend)] if { var(txn.saml.saml_app_backend) -m found }
       # ------------------------
       # ----end SAML section----
       # ------------------------

     hapee-lb.cfg
     haproxy
     frontend fe_main
       bind :80
       bind :443 ssl crt /etc/hapee-3.0/ssl/cert.pem
       mode http
       option http-buffer-request
       tcp-request inspect-delay 5s
       
       # --------------------
       # ----SAML section----
       # --------------------
       http-request saml-sso MySAMLApp if { hdr(host) -i example.com }
       http-response saml-sso MySAMLApp
       default_backend bk-err
       use_backend %[var(txn.saml.saml_app_backend)] if { var(txn.saml.saml_app_backend) -m found }
       # ------------------------
       # ----end SAML section----
       # ------------------------

6. Add two backend sections:

   • A backend named bk-err for when there are errors:

     hapee-lb.cfg
     haproxy
     backend bk-err
       mode http

     hapee-lb.cfg
     haproxy
     backend bk-err
       mode http

   • A backend for your load balanced servers. The name should begin with bk- and end with the saml.ini section name (for example, MySAMLApp):

     hapee-lb.cfg
     haproxy
     backend bk-MySAMLApp
       option forwardfor
       server app1 127.0.0.1:8000

     hapee-lb.cfg
     haproxy
     backend bk-MySAMLApp
       option forwardfor
       server app1 127.0.0.1:8000

7. Restart the HAProxy Enterprise service.

   nix
   sudo systemctl restart hapee-3.0-lb

   nix
   sudo systemctl restart hapee-3.0-lb

   You can then make requests to your application at the FQDN you configured and you will be redirected to the IdP login page. Be sure to use HTTPS if that is what you set for the Reply URL.

Verify the signature of the SAML Response Jump to heading #

When Azure sends its SAML response that contains the information HAProxy Enterprise needs to authorize a user to access an application, it is sending an XML token. To prove that it is the trusted issuer of that token, it digitally signs it with its secret key. We recommend that you verify that key using the key’s associated public X.509 certificate.

To enable signature verification:

1. Sign in to the Azure portal.

2. Search for and select Microsoft Entra ID. If you manage multiple tenants, then choose Manage tenants and then select the tenant with which you would like to enable single sign-on.

3. From the Microsoft Entra ID Overview page, choose Enterprise applications, select your application, then select Single sign-on in the left-hand menu.

4. From the Set up Single Sign-On with SAML screen, edit the SAML Certificates. Ensure that Signing Option is set to Sign SAML response and assertion and that Signing Algorithm is set to SHA-256.

5. From the SAML Certificates section, download the certificate (Base64 format). This downloads a file with a .cer extension. Copy this file to your HAProxy Enterprise load balancer.

6. On the HAProxy Enterprise server, edit the file saml.ini.

   Uncomment (remove the preceding semicolon) the lines idp_public_cert and verify_signature. Set idp_public_cert to the path of the certificate from your Microsoft Entra ID enterprise application.

   Below, we enable signature verification using your application’s certificate:

   saml.ini
   ini
   idp_public_cert = /etc/hapee-3.0/samlapp.cer
   verify_signature=1

   saml.ini
   ini
   idp_public_cert = /etc/hapee-3.0/samlapp.cer
   verify_signature=1

7. Restart the HAProxy Enterprise service.

   nix
   sudo systemctl restart hapee-3.0-lb

   nix
   sudo systemctl restart hapee-3.0-lb

Set headers and variables from attributes Jump to heading #

If the user authenticates successfully via the IdP, the IdP sends a SAMLResponse back to the SP. Part of the response is the AttributeStatement, which holds attributes like the user’s given name, surname, and email address. To see those attributes, you can set response headers that contain them. The SAML module will create the response headers automatically if you use the on_saml_response check_attr action with the set_var option.

1. Start by getting a list of assertions that are available in the AttributeStatement. Use set_var to get all of the names. Add this to your saml.ini file:

   saml.ini
   ini
   ; Get all the SAML attributes names
   on_saml_response check_attr set_var=all_attributes_names  set_var_sep=| xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute/@Name

   saml.ini
   ini
   ; Get all the SAML attributes names
   on_saml_response check_attr set_var=all_attributes_names  set_var_sep=| xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute/@Name

2. Use your browser’s Dev tools to inspect the response after logging in successfully. Below, we see that a response header named All_attributes_names names has been added and contains all of the attributes (line breaks added for readability):

   text
   All_attributes_names: http://schemas.microsoft.com/identity/claims/tenantid|
     http://schemas.microsoft.com/identity/claims/objectidentifier|
     http://schemas.microsoft.com/identity/claims/displayname|
     http://schemas.microsoft.com/identity/claims/identityprovider|
     http://schemas.microsoft.com/claims/authnmethodsreferences|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name|

   text
   All_attributes_names: http://schemas.microsoft.com/identity/claims/tenantid|
     http://schemas.microsoft.com/identity/claims/objectidentifier|
     http://schemas.microsoft.com/identity/claims/displayname|
     http://schemas.microsoft.com/identity/claims/identityprovider|
     http://schemas.microsoft.com/claims/authnmethodsreferences|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress|
     http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name|

3. Add on_saml_response check_attr set_var lines for the attributes you want. Below, we get the attribute displayname:

   saml.ini
   ini
   on_saml_response check_attr set_var=display_name xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name='http://schemas.microsoft.com/identity/claims/displayname']/saml:AttributeValue/text()

   saml.ini
   ini
   on_saml_response check_attr set_var=display_name xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name='http://schemas.microsoft.com/identity/claims/displayname']/saml:AttributeValue/text()

   The response will then include a header named display_name:

   text
   Display_name: Joe Example

   text
   Display_name: Joe Example

4. Attributes you capture with the set_var option are also made available as variables in your load balancer configuration. For example, the display_name variable becomes available as txn.saml.display_name. Below, we add it to the access log:

   hapee-lb.cfg
   haproxy
   frontend fe_main
     log-format "$HAPROXY_HTTP_LOG_FMT display_name=%[var(txn.saml.display_name)]"

   hapee-lb.cfg
   haproxy
   frontend fe_main
     log-format "$HAPROXY_HTTP_LOG_FMT display_name=%[var(txn.saml.display_name)]"

Log out Jump to heading #

Users can log out of your application by visiting the /saml/logout URL path, such as https://example.com/saml/logout. This will send a LogoutRequest to the IdP, and then the IdP will send the user back to the application for local logout of the app. Successful logouts will set the variable txn.saml.saml_logout_ok to 1.

Considerations:

• If your browser blocks the logout cookie, which will often come from a different domain, then you can set the saml_cookie_samesite directive to None.

SAML configuration reference Jump to heading #

This section describes the syntax of the file saml.ini.

Directives Jump to heading #

The saml.ini file configures how the SAML module integrates with the SAML identity provider. It supports the following configuration directives.

Actions Jump to heading #

In the saml.ini file, actions let you validate the schema, set variables, and other tasks.

Action flags Jump to heading #

Actions accept the following flags:

Troubleshooting Jump to heading #

This section covers ways to troubleshoot the SAML module.

Start a debug trace Jump to heading #

To get a verbose log of the authentication process, which includes the full SAMLResponse, enable these traces:

nix
(echo "trace saml-sso sink buf0; trace saml-sso level developer; trace saml-sso verbosity complete; trace saml-sso start now; show events buf0 -w" ; cat ) | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

nix
(echo "trace saml-sso sink buf0; trace saml-sso level developer; trace saml-sso verbosity complete; trace saml-sso start now; show events buf0 -w" ; cat ) | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

To stop the traces, call this command:

nix
(echo "trace saml-sso stop now") | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

nix
(echo "trace saml-sso stop now") | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

Redirect loops Jump to heading #

If you try to access a resource and get redirected back and forth between your application and the IdP, it could be that your browser is not sending back the cookie that the SAML component just set.

• Check your saml_cookie_secure setting. If it is set to 1, your browser will only use the cookie when using HTTPS, not plain HTTP.
• Check your saml_cookie_domain and make sure it matches the domain of your application.
• In some situations, excessively strict security settings of your browsers can also prevent the cookie from being sent to your application. Also, you might need to set the saml_cookie_samesite value to None (which may also require setting saml_cookie_secure to 1 on browsers).