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

The SAML module uses the Stream Processing Offload Engine to communicate with the load balancer using the Stream Processing Offload Protocol.

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 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 and then add a new 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 Properties page.
   Application ID	On the enterprise application’s Properties 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 SAML module via your system’s package manager.

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-extras-spoa-saml20

   nix
   sudo apt-get install hapee-extras-spoa-saml20

   nix
   sudo yum install hapee-extras-spoa-saml20

   nix
   sudo yum install hapee-extras-spoa-saml20

   nix
   sudo zypper install hapee-extras-spoa-saml20

   nix
   sudo zypper install hapee-extras-spoa-saml20

   nix
   sudo pkg install hapee-extras-spoa-saml20

   nix
   sudo pkg install hapee-extras-spoa-saml20

2. This creates the folder /etc/hapee-extras/saml_examples/azure. Copy the files from that folder to /etc/hapee-extras/. 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.
   {{IDP_APP_ID}}	Your Microsoft Entra ID enterprise application’s Application ID.
   {{IDP_TENANT_ID}}	Your Microsoft Entra ID Tenant ID.
   {{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-2.8/hapee-lb.cfg.

   Copy the SAML section below into the frontend section for your load balanced application. Modify the line that sets the variable sess.saml_app to match the app name in saml.ini (for example, MySAMLApp), and change the if statement to use your fully qualified domain name. The rest does not need to be changed.

   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-2.8/ssl/cert.pem
     mode http
     option http-buffer-request
     tcp-request inspect-delay 5s
     
     # --------------------
     # ----SAML section----
     # --------------------
     # here, replace MySAMLApp and the if statement with correct FQDN, depending on your setup
     http-request set-var(sess.saml_app) str(MySAMLApp) if { hdr(host) -i example.com }
     
     filter spoe engine spoe-saml config /etc/hapee-extras/hapee-saml-spoe.cfg
     
     http-request send-spoe-group spoe-saml spoe-group-req
     http-request redirect location %[var(txn.saml.redirect_to)] code 302 if { var(txn.saml.redirect_to) -m found }
     http-request deny if ! { var(txn.saml.saml_auth_ok) -m bool } ! { var(txn.saml.saml_logout_ok) -m bool }
     
     http-response set-header Set-Cookie %[var(txn.saml.set_cookie)] if { var(txn.saml.set_cookie) -m found }
     http-response set-header saml-auth-error-text %[var(txn.saml.saml_auth_error_text)] if { var(txn.saml.saml_auth_error_text) -m found }
     http-response set-header location %[var(txn.saml.redirect_after_auth)] if { var(txn.saml.redirect_after_auth)  -m found }
     http-response set-status 303 if { var(txn.saml.redirect_after_auth)  -m found }
     # ------------------------
     # ----end SAML section----
     # ------------------------
     
     # The backend to send authenticated requests to
     default_backend webservers

   hapee-lb.cfg
   haproxy
   frontend fe_main
     bind :80
     bind :443 ssl crt /etc/hapee-2.8/ssl/cert.pem
     mode http
     option http-buffer-request
     tcp-request inspect-delay 5s
     
     # --------------------
     # ----SAML section----
     # --------------------
     # here, replace MySAMLApp and the if statement with correct FQDN, depending on your setup
     http-request set-var(sess.saml_app) str(MySAMLApp) if { hdr(host) -i example.com }
     
     filter spoe engine spoe-saml config /etc/hapee-extras/hapee-saml-spoe.cfg
     
     http-request send-spoe-group spoe-saml spoe-group-req
     http-request redirect location %[var(txn.saml.redirect_to)] code 302 if { var(txn.saml.redirect_to) -m found }
     http-request deny if ! { var(txn.saml.saml_auth_ok) -m bool } ! { var(txn.saml.saml_logout_ok) -m bool }
     
     http-response set-header Set-Cookie %[var(txn.saml.set_cookie)] if { var(txn.saml.set_cookie) -m found }
     http-response set-header saml-auth-error-text %[var(txn.saml.saml_auth_error_text)] if { var(txn.saml.saml_auth_error_text) -m found }
     http-response set-header location %[var(txn.saml.redirect_after_auth)] if { var(txn.saml.redirect_after_auth)  -m found }
     http-response set-status 303 if { var(txn.saml.redirect_after_auth)  -m found }
     # ------------------------
     # ----end SAML section----
     # ------------------------
     
     # The backend to send authenticated requests to
     default_backend webservers

6. Add a backend section for the SAML module service. HAProxy Enterprise uses this when authenticating requests.

   Below, we add a backend for the SAML module service:

   hapee-lb.cfg
   haproxy
   backend bk-spoe
     mode tcp
     timeout connect 5s
     timeout server 30s
     server auth-server-spoe 127.0.0.1:12345

   hapee-lb.cfg
   haproxy
   backend bk-spoe
     mode tcp
     timeout connect 5s
     timeout server 30s
     server auth-server-spoe 127.0.0.1:12345

7. Enable and start the SAML module service.

   nix
   sudo systemctl enable hapee-extras-spoa-saml
   sudo systemctl start hapee-extras-spoa-saml

   nix
   sudo systemctl enable hapee-extras-spoa-saml
   sudo systemctl start hapee-extras-spoa-saml

8. Restart the HAProxy Enterprise service.

   nix
   sudo systemctl restart hapee-2.8-lb

   nix
   sudo systemctl restart hapee-2.8-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.

Optional: 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. You can 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, such as to /etc/hapee-extras/.

6. On the HAProxy Enterprise server, edit the file /etc/hapee-extras/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-extras/samlapp.cer
   verify_signature=1

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

7. Restart the SAML service.

   nix
   sudo systemctl restart hapee-extras-spoa-saml

   nix
   sudo systemctl restart hapee-extras-spoa-saml

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 #

Show status of service Jump to heading #

Check the status of the SAML module service, which will show any errors it encountered while validating SAML responses.

nix
sudo systemctl status hapee-extras-spoa-saml.service

nix
sudo systemctl status hapee-extras-spoa-saml.service

Cannot redirect to the IdP form, we already come from it…

• There might be a protocol mismatch. If you have an HTTPS proxy in front of the load balancer, but the load balancer itself is not listening on HTTPS, then change it so that the load balancer listens on HTTPS.

• The URI sent to the SAML service may be wrong, causing validation of the SAML response to fail. In older versions of the module, the configuration file /etc/hapee-extras/hapee-saml-spoe.cfg passed the uri argument with the wrong value It looked like this:

  ini
  uri=url

  ini
  uri=url

  Change it to:

  ini
  uri=pathq

  ini
  uri=pathq

Cannot find config for application “MySAMLApp”

• Ensure that your changes to the saml.ini file took effect by restarting the saml service.

Debug mode Jump to heading #

The SAML module can be launched in full debug mode:

nix
systemctl stop hapee-extras-spoa-saml.service
/opt/hapee-extras/bin/hapee-saml -F -f /etc/hapee-extras/saml.ini --debug-all

nix
systemctl stop hapee-extras-spoa-saml.service
/opt/hapee-extras/bin/hapee-saml -F -f /etc/hapee-extras/saml.ini --debug-all

When you are in debug mode, the SAMLResponse is printed in clear.

Testing XPath expressions Jump to heading #

When you are in debug mode, you can save SAML responses to a text file. Then use xmllint (found in the libxml2 package) to test XPath expressions:

nix
xmllint --shell SAMLResponse.xml
setns saml=urn:oasis:names:tc:SAML:2.0:assertion
setns samlp=urn:oasis:names:tc:SAML:2.0:protocol
xpath /samlp:Response/@Destination

nix
xmllint --shell SAMLResponse.xml
setns saml=urn:oasis:names:tc:SAML:2.0:assertion
setns samlp=urn:oasis:names:tc:SAML:2.0:protocol
xpath /samlp:Response/@Destination

You may also find other useful XPath testers online.

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 you 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).