HAProxy Enterprise Documentation 2.5r1

Install the HAProxy Enterprise SAML module for Azure Active Directory

The single sign-on configuration described in this section uses Azure Active Directory as the Identity Provider. The HAProxy Enterprise SAML module is the Service Provider.

Create an Azure Active Directory enterprise application

To configure Azure Active Directory to serve as the Identity Provider for single sign-on:

Sign in to the Azure portal.
Search for and select Azure Active Directory. If you manage multiple Active Directory tenants, then choose Manage tenants and then select the tenant with which you would like to enable single sign-on.
From the Azure Active Directory dashboard, choose Enterprise applications and then add a new application.
On the Browse Azure AD 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.

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

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 Azure Active Directory. For example, https://example.com/saml/logout.

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 Azure Active Directory. For example, `https://example.com/saml/logout`.

Save and then close the basic SAML configuration panel.

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.

You will need several properties of your Azure Active Directory 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 Azure Active Directory Overview page

Configure the HAProxy Enterprise SAML module

On your HAProxy Enterprise load balancer, install the SAML module via your system's package manager.

$ # On Debian/Ubuntu
$ sudo apt-get install hapee-extras-spoa-saml

$ # On CentOS/RedHat/Oracle/Photon OS
$ sudo yum install hapee-extras-spoa-saml

$ # On SUSE
$ sudo zypper install hapee-extras-spoa-saml

$ # On FreeBSD
$ sudo pkg install hapee-extras-spoa-saml

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

Edit the copied file saml.ini. At the top of the file, change the values of the following fields to match your Azure Active Directory enterprise application's properties:

Property	Set it to
`{{ID_APP_NAME}}`	Your Azure AD enterprise application's Name.
`{{IDP_APP_ID}}`	Your Azure AD enterprise application's Application ID.
`{{IDP_TENANT_ID}}`	Your Azure Active Directory 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.

An example portion of the saml.ini configuration.

[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}}

Edit the HAProxy Enterprise configuration file, /etc/hapee-2.5/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.

Add the directives to enable SAML single sign-on in the frontend.

frontend fe_main
   bind :80
   bind :443 ssl crt /etc/hapee-2.5/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

Add a backend section for the SAML module service. HAProxy Enterprise uses this when authenticating requests.
Add a backend for the SAML module service.
```
backend bk-spoe
   mode tcp
   timeout connect 5s
   timeout server 30s
   server auth-server-spoe 127.0.0.1:12345
```

Enable and start the SAML module service.

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

Restart the HAProxy Enterprise service.
```
$ sudo systemctl restart hapee-2.5-lb
```
You can then make requests to your application and you will be redirected to the Azure login page.

Optional: Verify the signature of the SAML Response

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:

Sign in to the Azure portal.
Search for and select Azure Active Directory. If you manage multiple Active Directory tenants, then choose Manage tenants and then select the tenant with which you would like to enable single sign-on.
From the Azure Active Directory dashboard, choose Enterprise applications, select your application, then select Single sign-on in the left-hand menu.
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.
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/.
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 Azure Active Directory enterprise application.
Enable signature verification using your application's certificate.
```
idp_public_cert = /etc/hapee-extras/samlapp.cer
verify_signature=1
```

Restart the SAML service.

$ sudo systemctl restart hapee-extras-spoa-saml

Log out

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 Azure Active Directory, and then Azure will send the user back to the application for local logout of the app.

Troubleshooting

Some steps to aid in troubleshooting:

Check the status of the SAML module service, which will show any errors it encountered while validating SAML responses.
```
$ sudo systemctl status hapee-extras-spoa-saml.service
```

Next up

SAML configuration options