Single sign-on (SAML)

HAProxy ALOHA’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 ALOHA 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.

You may find the following resources helpful for learning SAML concepts:

• Microsoft’s guide: SAML authentication with Microsoft Entra ID
• Okta’s SAML guide

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 for Microsoft Entra ID Jump to heading #

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

This section describes how to configure the SAML module specifically for Microsoft Entra ID.

1. Open a terminal window and connect to HAProxy ALOHA by going to Tools and clicking Launch a terminal.

   Copy the Microsoft Entra ID example files into /etc/saml/:

   nix
   sudo cp /usr/share/factory/base-etc/haproxy/extra/saml/saml_examples/azure/* /etc/saml/

   nix
   sudo cp /usr/share/factory/base-etc/haproxy/extra/saml/saml_examples/azure/* /etc/saml/

   The files include:

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

2. In the Services tab, click saml setup. The SAML service’s setup file displays.

   Remove the line no autostart. Click OK and Close. Then apply the changes by clicking Apply new configuration on the Services screen.

3. In the Services tab, click [advanced mode]. Then edit the saml configuration. This displays the contents of the /etc/saml/saml.ini file.

   • 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 ALOHA 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}}                      
     

   • Change the following lines so that they point to the /etc/saml directory:

     saml.ini
     ini
     authn_request_template_filename = /etc/saml/authn_request.xml
     logout_request_template_filename = /etc/saml/logout_request.xml

     saml.ini
     ini
     authn_request_template_filename = /etc/saml/authn_request.xml
     logout_request_template_filename = /etc/saml/logout_request.xml

   • For a production environment, we also recommend enabling the require_signed_assertion, require_signed_response, and saml_cookie_secure directives.

     ini
     require_signed_assertion 1
     require_signed_response 1
     saml_cookie_secure 1

     ini
     require_signed_assertion 1
     require_signed_response 1
     saml_cookie_secure 1

   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. Click OK and then Close. Then apply the changes by clicking Apply new configuration on the Services screen.

5. Restart the saml service.

6. On the LB Layer7 tab, copy the SAML section shown 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. The frontend must be in HTTP mode.

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

   haproxy
   frontend fe_main
     bind 0.0.0.0:80 name http 
     bind 0.0.0.0:443 name https ssl crt example alpn h2,http/1.1
     mode http
     
     # --------------------
     # ----SAML section----
     # --------------------
     option http-buffer-request
     tcp-request inspect-delay 5s
     # 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/haproxy/extra/saml/haproxy-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

   haproxy
   frontend fe_main
     bind 0.0.0.0:80 name http 
     bind 0.0.0.0:443 name https ssl crt example alpn h2,http/1.1
     mode http
     
     # --------------------
     # ----SAML section----
     # --------------------
     option http-buffer-request
     tcp-request inspect-delay 5s
     # 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/haproxy/extra/saml/haproxy-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

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

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

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

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

8. Click OK and then Apply to save the configuration.

9. To make the changes persist after a reboot, go to the Setup tab and click Save within the Configuration section.

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 ALOHA 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 ALOHA load balancer, such as to /etc/saml/.

6. In the Services tab, click [advanced mode]. Then edit the saml configuration. This displays the contents of the /etc/saml/saml.ini file.

   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/saml/samlapp.cer
   verify_signature=1

   saml.ini
   ini
   idp_public_cert = /etc/saml/samlapp.cer
   verify_signature=1

7. Click OK and then Close. Then apply the changes by clicking Apply new configuration on the Services screen.

8. Restart the saml service.

9. To make the changes persist after a reboot, go to the Setup tab and click Save within the Configuration section.

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 #

Service status Jump to heading #

Check the status of the SAML module service via the systems logs on the Logs tab, which will show any errors it encountered while validating SAML responses.

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/haproxy/extra/saml/haproxy-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 #

To perform troubleshooting, the SAML module can be launched in full debug mode:

• In the Services tab, click saml setup. The SAML service’s setup file displays.
• Add the line debug --debug-all. Click OK and Close.
• Apply the changes by clicking Apply new configuration on the Services screen.

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