Features

• Implement SSO seamlessly, even for legacy web applications

• Configure logging and grant access thanks to the HAProxy Enterprise ACL syntax

• Check SAML assertions or attributes with XPath

• Retrieve SAML assertions and use them as HAProxy Enterprise variables. For example, you can then:

  • Grant access to a group of users

  • Enhance logs

  • Pass user information to the application via HTTP headers

Architecture

HAProxy Enterprise SAML Component expands the functionalities of HAProxy Enterprise thanks to the Stream Processing Offload Engine.

HAProxy Enterprise SAML Component is a Stream Processing Offload Agent. It communicates with HAProxy Enterprise using the Stream Processing Offload Protocol.

Concepts and workflows

Single sign-on using SAML in a Web browser

The SSO workflow using a Web browser is as follows:

Prerequisites

To use HAProxy Enterprise SAML Component, you must have access to a SAML Identity Provider such as Azure Active Directory, Okta, Ping, or Microsoft ADFS, on-premises or in the cloud.

Installing HAProxy Enterprise SAML Component

Install HAProxy Enterprise SAML Component via your package manager.

See also

Installing HAProxy Enterprise 1.9r1

Creating an Azure Active Directory enterprise application

Perform the steps below on the Azure portal.

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

2. In Microsoft Azure, create a new non-gallery enterprise application in Azure Active Directory.

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

Exporting the tenant ID and usernames

Perform the steps below on the Azure portal.

1. Navigate to Azure Active Directory, then write down your tenant ID.

2. Write down the first name of one or several users who have access to your Azure Active Directory enterprise application from their user profiles.

   We will whitelist users later on.

Setting up the basic SAML configuration

Perform the steps below on the Azure portal.

1. Select Sign-on, then click SAML.

   

   The Set up Single Sign-On with SAML page appears.

   

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

   This ID can only contain alphanumeric characters and underscores (_).

   samlappaugust11

   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

Creating a sample local application

Perform the steps below on the Ubuntu VM.

We will set up an NGINX instance on the virtual machine as a sample application. It will listen on localhost on port 3200 and will not be SAML-enabled on its own.

1. Install NGINX:

   ubuntu@vm:~$ sudo apt install nginx -y

2. Customize the NGINX welcome page:

   ubuntu@vm:~$ sudo sed -i 's/Welcome to nginx/My SAML application/' \
   /var/www/html/index.nginx-debian.html

3. Make the NGINX instance listen on port 3200:

   ubuntu@vm:~$ sudo sed -i 's/80/3200/' /etc/nginx/sites-enabled/default

   ubuntu@vm:~$ sudo systemctl restart nginx

Creating variables

Perform the steps below on the Ubuntu VM.

1. Add the following variables to a new variables.txt file:

   export myazureapp=<Your Azure application's name>
   export idp_app_id=<Your Azure application ID>
   export idp_tenant_id=<Your Azure Active Directory tenant ID>
   export myappfqdn=<Your sample local application's FQDN>
   export myappsocketpadress=<Your sample local application's IP:port>
   export samlapp=<Internal name for your sample local application>
   export samlappusers=<Space delimited list of users' first names>
   export lbipaddress=<HAProxy Enterprise's IP address>
   export hapeeversion=<HAProxy Enterprise Major Version Number>
   export hapeekey=<HAProxy Enterprise Key>

   ubuntu@vm:~$ cat <<EOF > variables.txt
   export myazureapp=samlappaugust11
   export idp_app_id=0000b000-00a0-0000-00c0-0000c000a0c0
   export idp_tenant_id=0fbb0000-0000-00ad-b00e-f00000000000
   export myappfqdn=app.example.local
   export myappsocketpadress=192.168.1.10:3200
   export samlapp="\$myazureapp"
   export samlappusers='Elena John Mary\\ Lou'
   export lbipaddress=127.0.0.1
   export hapeeversion=1.9
   export hapeekey=xxxxxxxx-xxxxxxxx
   EOF

Installing required packages

Perform the steps below on the Ubuntu VM.

1. Install cURL, HAProxy Enterprise, and HAProxy Enterprise SAML Component:

   ubuntu@vm:~$ source variables.txt

   ubuntu@vm:~$ sudo apt install curl -y

   ubuntu@vm:~$ curl -s https://cdn.haproxy.com/static/install_haproxy_enterprise.sh |
   sudo bash /dev/stdin 1.9r1 $hapeekey

   ubuntu@vm:~$ sudo apt install hapee-extras-spoa-saml -y

Creating a self-signed SSL certificate

Perform the steps below on the Ubuntu VM.

1. Create a self-signed SSL certificate to allow connecting via HTTPS:

   ubuntu@vm:~$ source variables.txt

   ubuntu@vm:~$ 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"

   Your sample local application's FQDN is used in the certificate Common Name. The certificate is valid only if the request hostname matches the common name.

2. Concatenate the key and the certificate into a new certificate:

   ubuntu@vm:~$ cat key.pem cert.pem |
   sudo tee /etc/hapee-$hapeeversion/certs/$samlapp.pem

Creating the HAProxy Enterprise configuration file

Perform the steps below on the Ubuntu VM.

The HAProxy Enterprise hapee-lb.cfg configuration file will contain:

• A SAML frontend to redirect user requests to HAProxy Enterprise SAML Component

• The three following backends:

  • A backend for the Stream Processing Offload Engine

  • A default backend to manage errors

  • A backend for your sample local application

1. Create the HAProxy Enterprise hapee-lb.cfg configuration file:

   The bind :443 ssl directive performs SSL termination on HAProxy Enterprise. You can then leverage HAProxy Enterprise to implement SSL in all your applications, whatever the underlying technologies.

   ubuntu@vm:~$ source variables.txt

   ubuntu@vm:~$ cat <<EOF | sudo tee /etc/hapee-2.1/hapee-lb.cfg
   frontend ft-saml
       bind :80
       bind :443 ssl crt /etc/hapee-$hapeeversion/certs/$samlapp.pem
       mode http
       option http-buffer-request
       tcp-request inspect-delay 10s
       timeout client 1m
       http-request set-var(sess.saml_app) str($samlapp)                            if { hdr(host) -i $myappfqdn }
       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-request set-header givenname             %[var(txn.saml.givenname)]
       http-request set-header display_name          %[var(txn.saml.display_name)]
       http-request set-header all_attributes_names  %[var(txn.saml.all_attributes_names)]
       http-request set-header all_attributes_values %[var(txn.saml.all_attributes_values)]
       http-request set-header AuthnInstant          %[var(txn.saml.AuthnInstant)]
       http-request set-header AuthnInstant_ts       %[var(txn.saml.AuthnInstant_ts)]
       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 }
   
       default_backend bk-err
       use_backend                                   %[var(txn.saml.saml_app_backend)]     if { var(txn.saml.saml_app_backend) -m found }
   
   backend bk-spoe
       mode tcp
       timeout connect 5s
       timeout server  30s
       server auth-server-spoe 127.0.0.1:12345
   
   backend bk-err
       mode http
   
   backend bk-$samlapp
       option forwardfor
       mode http
       server $samlapp $myappsocketpadress
       timeout connect 30s
       timeout server 1m
   EOF

Creating the HAProxy Enterprise SAML Component initialization file

Perform the steps below on the Ubuntu VM.

1. Create the HAProxy Enterprise SAML Component saml.ini initialization file:

   ubuntu@vm:~$ source variables.txt

   ubuntu@vm:~$ cat <<EOF | sudo tee /etc/hapee-extras/saml.ini
   config_version = 1.0.0
   
   [$samlapp]
   {{IDP_APP_NAME}} = $myazureapp
   {{IDP_APP_ID}} = $idp_app_id
   {{IDP_TENANT_ID}} = $idp_tenant_id
   {{CLAIM_PREFIX}} = http://schemas.xmlsoap.org/ws/2005/05/identity/claims
   
   {{APP_FQDN}} = $myappfqdn
   {{APP_LOGIN_URL}} = https://{{APP_FQDN}}/saml/reply
   {{APP_LOGOUT_URL}} = https://{{APP_FQDN}}/saml/logout
   {{APP_BACKEND}} = bk-{{APP_NAME}}
   
   saml_cookie_secure = 0
   saml_cookie_samesite = Lax
   saml_cookie_httponly = 0
   saml_cookie_lifetime = 3600
   saml_cookie_time_offset = 0
   saml_cookie_domain = {{APP_FQDN}}
   authn_request_template_filename = authn_request.xml
   logout_request_template_filename = logout_request.xml
   saml_app_backend = {{APP_BACKEND}}
   
   sign_authn_requests=0
   sign_logout_requests=0
   verify_signature=0
   
   app_login_url = {{APP_LOGIN_URL}}
   app_logout_url = {{APP_LOGOUT_URL}}
   
   idp_login_url = https://login.microsoftonline.com/{{IDP_TENANT_ID}}/saml2
   idp_logout_url = https://login.microsoftonline.com/logout.srf
   
   ; this field is also used to detect redirect loops between the IDp and our app
   idp_referer_url = https://login.microsoftonline.com/
   on_saml_response check_schema
   on_saml_response check_attr entity_id spn:{{IDP_APP_ID}}
   on_saml_response check_attr version
   on_saml_response check_attr status_code
   on_saml_response check_attr issuer https://sts.windows.net/{{IDP_TENANT_ID}}/
   on_saml_response check_attr issue_instant
   on_saml_response check_attr destination {{APP_LOGIN_URL}}
   on_saml_response check_attr assertion required_count=1
   on_saml_response check_conditions required_count=1
   on_saml_response check_subject_confirmation_data required_count=1
   
   ; Get all the SAML attributes names
   on_saml_response check_attr set_var=all_attributes_names  set_var_sep=| xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute/@Name
   
   ; Get all the SAML attributes values
   on_saml_response check_attr set_var=all_attributes_values set_var_sep=| xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute/saml:AttributeValue/text()
   
   ; Get the User Display Name provided in SAML Responses or Logout Requests
   on_saml_response check_attr set_var=display_name xpath=/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name='http://schemas.microsoft.com/identity/claims/displayname']/@Name
   
   on_saml_response check_attr set_var=AuthnInstant_ts xpath=/samlp:Response/saml:Assertion/saml:AuthnStatement/@AuthnInstant set_var_as_timestamp
   on_saml_response check_attr set_var=AuthnInstant    xpath=/samlp:Response/saml:Assertion/saml:AuthnStatement/@AuthnInstant
   
   on_logout_request check_attr set_var=display_name xpath=/samlp:LogoutRequest/saml:NameID/text()
   on_logout_request check_attr destination {{APP_LOGOUT_URL}} required
   on_logout_request check_attr issuer https://sts.windows.net/{{IDP_TENANT_ID}}/ required
   EOF

Creating the Microsoft Azure templates

Perform the steps below on the Ubuntu VM.

1. Copy the Microsoft Azure example authentication request and logout request templates to the HAProxy Enterprise configuration directory:

   ubuntu@vm:~$ sudo cp /etc/hapee-extras/saml_examples/azure/authn_request.xml \
   /etc/hapee-extras/

   ubuntu@vm:~$ sudo cp /etc/hapee-extras/saml_examples/azure/logout_request.xml \
   /etc/hapee-extras/

Troubleshooting

Perform the steps below on the Ubuntu VM.

If an error occurs:

1. Stop HAProxy Enterprise SAML Component:

   ubuntu@vm:~$ sudo service saml stop

   # Stopping spoa-saml (pid 8831 according to /var/run/saml.pid) ...
     Waiting..
      --> removing stale pid file ...
     ==> stop spoa-saml Done.

2. Start HAProxy Enterprise SAML Component in debug mode:

   ubuntu@vm:~$ /opt/hapee-extras/bin/hapee-saml -C /etc/hapee-extras/ \
   -f /etc/hapee-extras/saml.ini --debug-all -F >> /tmp/log_file 2>&1

3. Repeat the steps that led to the error, then analyze the /tmp/log_file file.

Whitelisting or blacklisting usernames

Perform the steps below on the Ubuntu VM.

You can whitelist or blacklist users at the Service Provider level, whatever the Identity Provider.

1. 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()'

   ubuntu@vm:~$ 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

2. Insert the following directive in the HAProxy Enterprise hapee-lb.cfg configuration file's frontend ft-saml section:

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

   ubuntu@vm:~$ sudo sed -i "/http-request deny/a        \    http-request deny if !        { var(txn.saml.$samlapp.givenname) $samlappusers }" /etc/hapee-2.1/hapee-lb.cfg

3. Restart HAProxy Enterprise and HAProxy Enterprise SAML Component:

   ubuntu@vm:~$ sudo systemctl reload hapee-1.9-lb

   ubuntu@vm:~$ sudo systemctl stop hapee-extras-spoa-saml

   ubuntu@vm:~$ sudo /opt/hapee-extras/bin/hapee-saml -C /etc/hapee-extras/ -f /etc/hapee-extras/saml.ini

4. Sign on to your sample local application with a whitelisted username, then with another username.

Frontend

frontend ft-saml
 bind :80
 bind :443 ssl crt mycert.pem
 mode http
 option http-buffer-request
 tcp-request inspect-delay 10s
 timeout client 1m
 http-request set-var(sess.saml_app) str(MySAMLApp) if { hdr(host) -i app.example.local }
 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-request set-header givenname             %[var(txn.saml.givenname)]
 http-request set-header displayname           %[var(txn.saml.displayname)]
 http-request set-header all_attributes_names  %[var(txn.saml.all_attributes_names)]
 http-request set-header all_attributes_values %[var(txn.saml.all_attributes_values)]
 http-request set-header AuthnInstant          %[var(txn.saml.AuthnInstant)]
 http-request set-header AuthnInstant_ts       %[var(txn.saml.AuthnInstant_ts)]
 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 }

Backends

Add the following backend sections:

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

backend bk-err
 mode http

default_backend bk-err

backend bk-MySAMLApp
 option forwardfor
 mode http
 server app1 127.0.0.1:3200
 timeout connect 30s
 timeout server 1m

Configuration options

Actions

Microsoft Azure HAProxy Enterprise SAML Component saml.ini initialization file example

This example is intended to be used with Microsoft Azure. To use HAProxy Enterprise SAML Component with other Identity Providers, this configuration file needs some adjustments.

Actions

Debug mode

If requests are denied or authentication fails, you can start the program with --debug-all -F to get more verbose output.

~$ hapee-saml -f /etc/hapee-extras/saml.ini --debug-all -F
  1586529662.886993 [00] Config version supported: 1.0.0
  1586529662.887347 [00] Config version 1.0.0
  1586529662.889158 [00] add namespace 0: samlp->urn:oasis:names:tc:SAML:2.0:protocol
  1586529662.889413 [00] add namespace 1: saml->urn:oasis:names:tc:SAML:2.0:assertion
  [...]

Testing XPath expressions

1. Run HAProxy Enterprise SAML Component in debug mode.

2. Save the SAML Response to a text file.

3. Use the xmllint command-line XML tool to test XPath expressions.

   The xmllint command is provided in the libxml2 package.

$ hapee-saml -f /etc/hapee-extras/saml.ini --debug-all -F >> log_file 2>&1

$ 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

Various online XPath test tools are available online. Be careful not to send confidential information.

Infinite loop

If an infinite loop between your application and the Identity Provider occurs when trying to access a resource, check your cookie_secure setting. If set to 1, your browser will only use the cookie for HTTPS, not for plain HTTP.

Also check your saml_cookie_domain and make sure it matches the domain of your application. Too strict security settings of your browsers can also prevent, in some situations, the cookie to be sent to your application. Also, you might need to set the saml_cookie_samesite value to None (which requires setting saml_cookie_secure to 1 on modern browsers).

Before you go into production

1. Set saml_cookie_secure to 1.

2. Enable XML signatures if supported by your Identity Provider and your setup.

3. Depending on how your Identity Provider handles logouts, ensure that the LogoutRequest is sent to your application along with a cookie.

4. Some Identity Providers' cookies (for example, Azure's) are regarded as third-party (these Identity Providers use an iframe to send the LogoutRequest to your application).

   These cookies might be blocked by your browser, depending on its configuration and the value of the SameSite cookie attribute.

   Set the SameSite to 0 or 1 via the saml_cookie_samesite configuration item.

5. To test logout, check that the LogoutRequest returns a 200 code and is received by your application.

   Successful LogoutRequests also set the txn.saml.saml_logout_ok HAProxy Enterprise variable to 1.