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
.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 variablesess.saml_app
to match the app name insaml.ini
(for example, MySAMLApp), and change theif
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.pemmode 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.cfghttp-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
andverify_signature
. Setidp_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.cerverify_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