HAProxy Enterprise Documentation 2.1r1
SAML Quick Start on Azure
This Quick Start Guide will guide you through setting up a sandbox HAProxy Enterprise SAML Component implementation in a Ubuntu 20.04 LTS local virtual machine
Warning
This setup is meant for test purposes only. Do not use it in a production environment.
We will enable single sign-on to a local NGINX instance. We will use Azure Active Directory as the Identity Provider. HAProxy Enterprise SAML Component will be the Service Provider.
Conventions
The procedures below use the following icons:

-
Perform the step in Microsoft Azure.

-
Perform the step in a Bash terminal.

-
Perform the step in a browser.
Create a sample local application
Create a new Ubuntu Desktop 20.04 LTS local virtual machine.
Log in to your new local virtual machine.
The procedures below will all take place on the local virtual machine.
We will set up an NGINX instance on the local virtual machine as a sample application. It will listen on localhost on port 3200 and will not be SAML-enabled on its own.
Note
In a production environment, your application would be hosted on a cluster of dedicated servers, on a private network.
Launch a terminal.
-
Install NGINX:
$ sudo apt install nginx -y
-
Make the NGINX instance listen on port 3200:
$ sudo sed -i 's/80/3200/' /etc/nginx/sites-enabled/default
$ sudo systemctl restart nginx
-
Connect to 127.0.0.1:3200
via a web browser.
The NGINX instance's welcome page displays.
You cannot access it via 127.0.0.1:80
. We will give access to the sample local application on port 80 later on via HAProxy Enterprise SAML Component.
Note
Though the security level provided by this implementation is very poor, it is enough to show the basics of setting up HAProxy Enterprise SAML Component.
Create an Azure Active Directory enterprise application
Launch a web browser, then sign in to the Microsoft Azure portal as a cloud application administrator, or as an application administrator for your Azure Active Directory tenant.
In Microsoft Azure, create a new non-gallery enterprise application in Azure Active Directory.
-
Add the following variables to your .bashrc
file:
$ echo 'myazureapp="<Your Azure application name>"' >> ~/.bashrc
$ echo 'idp_app_id="<Your Azure application ID>"' >> ~/.bashrc
We will use these variables later on to configure HAProxy Enterprise and HAProxy Enterprise SAML Component.
Click Assign users and groups, and grant access to the Azure Active Directory enterprise application to one or several users.
See also
Add an unlisted (non-gallery) application to your Azure AD organization
Set up the SAML parameters
-
Add a variable for your sample local application's FQDN to your .bashrc
file:
$ echo 'myappfqdn="<Your sample local application FQDN>"' >> ~/.bashrc
$ echo 'myappfqdn="app.example.local"' >> ~/.bashrc
-
Select Sign-on, then click SAML.
The Set up Single Sign-On with SAML page appears.
-
Edit the Basic SAML Configuration:
- Identifier (Entity ID)
-
Enter a SAML ID for your application. For the sake of simplicity, enter your Azure Active Directory enterprise application's name, which corresponds to the value of the $myazureapp
variable.
- Reply URL (Assertion Consumer Service URL)
-
Enter https://<Your sample local application's FQDN>/saml/reply
.
https://app.example.local/saml/reply
- Logout Url
-
Enter https://<Your sample local application's FQDN>/saml/logout
.
https://app.example.local/saml/logout
Export the certificate and the tenant ID
Click the pencil in the SAML Signing Certificate area, then select Sign SAML response and assertion in the Signing option drop-down.
-
Download the Azure Openssl PEM format Base64 Azure Active Directory enterprise application' certificate.
For instance samlappjuly1.cer
.
Navigate to Azure Active Directory, then copy your tenant ID.
-
Add a variable for your tenant ID to your .bashrc
file:
$ echo 'idp_tenant_id="<Your Azure Active Directory tenant ID>"' >> ~/.bashrc
Install HAProxy Enterprise with SAML components
-
Add the following variables to your .bashrc
file:
$ echo 'hapeekey="<HAProxy Enterprise Key>"' >> ~/.bashrc
$ echo 'hapeeversion="<HAProxy Enterprise version>"' >> ~/.bashrc
$ echo 'samlapp="<Internal name for your sample local application>"' >> ~/.bashrc
Variable | Value | Example |
hapeekey | HAProxy Enterprise key you received when you registered. | xxxxxxxx-xxxxxxxx |
hapeeversion | HAProxy Enterprise version number. | 2.1 |
samlapp | Application configured in the HAProxy Enterprise SAML Component saml.ini initialization file You can create several sections. Each section corresponds to an application. | MySAMLApp |
Note
The internal name for your sample local application can only contain alphanumeric characters and underscores (_
).
-
Reload your .bashrc
file to take into account the variables you've created:
-
Install cURL, OpenSSL, HAProxy Enterprise, and HAProxy Enterprise SAML Component:
This step uses the following variable:
$hapeekey
| HAProxy Enterprise key you received when you registered |
$ sudo apt install curl openssl -y
$ curl -s https://www.haproxy.com/static/install_haproxy_enterprise.sh | sudo bash /dev/stdin 2.1r1 $hapeekey
$ sudo apt install hapee-extras-spoa-saml -y
Manage the HAProxy Enterprise SAML Component and Microsoft Azure certificates
-
Create a self-signed SSL certificate to allow connecting via HTTPS, then copy the certificate and the key to the right directory, with the right ownership:
This step uses the following variables:
$hapeeversion
| HAProxy Enterprise version used in paths |
$myappfqdn
| Your sample local application's FQDN, used in the certificate Common Name. The certificate is valid only if the request hostname matches the common name. |
$ sudo openssl req -keyout key.pem -out cert.pem -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj "/C=FR/ST=IdF/L=Paris/O=HAProxy Technologies/OU=IT/CN=$myappfqdn"
$ sudo cat key.pem cert.pem | sudo tee -a /etc/hapee-$hapeeversion/certs/mycert.pem
$ sudo cp key.pem /etc/hapee-extras/
$ sudo chmod 744 /etc/hapee-extras/key.pem
-
Copy your Azure Active Directory enterprise application certificate to /etc/hapee-extras/
, then make the current user the owner of the certificate:
$ sudo cp ~/Download/$myazureapp.cer /etc/hapee-extras/
$ sudo chmod 744 /etc/hapee-extras/$myazureapp.cer
Start HAProxy Enterprise and the HAProxy Enterprise SAML Component
Start HAProxy Enterprise and HAProxy Enterprise SAML Component:
This step uses the following variable:
$hapeeversion
| HAProxy Enterprise version used in paths and binary files names |
$ sudo systemctl enable hapee-extras-spoa-saml
$ sudo systemctl start hapee-extras-spoa-saml
$ sudo systemctl enable hapee-$hapeeversion-lb
$ sudo systemctl start hapee-$hapeeversion-lb
Connect to your sample local application
-
Redirect your NGNIX instance's Fully Qualified Domain Name to 127.0.0.1
in the /etc/hosts
file:
This step uses the following variable:
$myappfqdn
| Your sample local application's FQDN |
$ echo "127.0.0.1 $myappfqdn" | sudo tee -a /etc/hosts
-
Connect to your sample local application's Fully Qualified Domain Name via a web browser.
Connect to http://app.example.local
or https://app.example.local
.
Note
Your NGINX instance listens on port 3200. You are then actually connecting to HAProxy Enterprise.
-
Sign on to the Microsoft Azure portal with your Microsoft Azure credentials.
The NGINX instance's welcome page displays.
Note
You can safely ignore the security warning that displays because we use a self-signed certificate.
Tip
If an error occurs, start HAProxy Enterprise SAML Component in debug mode:
$ /opt/hapee-extras/bin/hapee-saml -C /etc/hapee-extras -f /etc/hapee-extras/saml.ini --debug-all -F
Allow or block usernames
You can allow or block users at the Service Provider level, whatever the Identity Provider.
Copy the first name of one or several users who have access to your Azure Active Directory enterprise application from their user profiles.
-
Add a variable for the list of authorized user's first names to your .bashrc
file:
$ echo 'samlappusers="<Space delimited list of users' first names>"' >> ~/.bashrc
Tip
You can escape spaces with the backslash character \. When creating the Bash variable, escape the backslash character itself with another one \\.
$ echo 'samlappusers="'Elena John Mary\\ Lou'"' >> ~/.bashrc
-
Reload your .bashrc
file to take into account the variables you've created:
-
Insert the following directive in the HAProxy Enterprise SAML Component saml.ini
initialization file:
on_saml_response check_subject_confirmation_data/a on_saml_response check_attr optional set_var_cnt set_var=givenname xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"]/saml:AttributeValue/text()'
$ sudo sed -i '/on_saml_response check_subject_confirmation_data/a on_saml_response check_attr optional set_var_cnt set_var=givenname xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"]/saml:AttributeValue/text()' /etc/hapee-extras/saml.ini
-
Insert the following directive in the HAProxy Enterprise hapee-lb.cfg
configuration file's frontend ft-saml
section:
frontend ft-saml
http-request deny if ! { var(txn.saml.<Internal name for your sample local application>.givenname) <Space delimited list of users' first names> }"
http-request deny if ! { var(txn.saml.MySAMLApp.givenname) Elena John Mary\ Lou }"
$ sudo sed -i "/http-request deny/a \ http-request deny if ! { var(txn.saml.$samlapp.givenname) $samlappusers }" /etc/hapee-$hapeeversion/hapee-lb.cfg
-
Restart HAProxy Enterprise and HAProxy Enterprise SAML Component:
$ sudo systemctl reload hapee-$hapeeversion-lb
$ sudo systemctl stop hapee-extras-spoa-saml
$ /opt/hapee-extras/bin/hapee-saml -C /etc/hapee-extras -f /etc/hapee-extras/saml.ini
Sign on to your sample local application with an allowed username, then with another username.
Tip
To block users, remove the !
sign before the condition.
Next up
SAML Reference