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:

  1. Sign in to the Azure portal.

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

  3. From the Azure Active Directory dashboard, choose Enterprise applications and then add a new application.

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

    https://cdn.haproxy.com/documentation/hapee/2-5r1/assets/azure-create-02822af126b71dbbb3ad29a6de28ce79398591176968df74b7fa9302e50d2778.png
  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 Azure Active Directory. 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 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

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

  3. 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}}
  4. 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
  5. 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
  6. Enable and start the SAML module service.

    $ sudo systemctl enable hapee-extras-spoa-saml
    $ sudo systemctl start hapee-extras-spoa-saml
  7. 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:

  1. Sign in to the Azure portal.

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

  3. From the Azure Active Directory dashboard, 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 Enterprise load balancer, such as to /etc/hapee-extras/.

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