HAProxy Enterprise Documentation 1.8r2

SAML

About SAML 2.0

The XML-based Security Assertion Markup Language (SAML) 2.0 open-standard transfers identity data (assertions) between an Identity Provider and a Service Provider.

Identity Provider

Performs authentication on the Service Provider's behalf.

Service Provider

Authorizes users to access the requested resource once they are authenticated by a trusted Identity Provider.

About HAProxy Enterprise SAML Component

HAProxy Enterprise SAML Component acts as a SAML Service Provider. It provides SP-initiated cross-domain web single-sign-on (SSO) to any web application located behind an HAProxy Enterprise server. You thus don't have to implement SAML directly in your application.

In an SP-initiated SSO flow, the Service Provider creates an Authentication Request (AuthnRequest) and redirects the user to the Identity Provider.

HAProxy Enterprise SAML Component checks user credentials against an Identity Provider such as Azure Active Directory, either on-premises or in the cloud.

https://cdn.haproxy.com/documentation/hapee/1-8r2/assets/saml-overview-0b981c0be508be6053aba8caf7c9b4d5f483dd7873740ce4238dbdee62b5124f.png

HAProxy Enterprise SAML Component then grants or denies access to web applications based on SAML assertions sent by the Identity Provider.

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:

https://cdn.haproxy.com/documentation/hapee/1-8r2/assets/saml-workflow-specs-764c22603d0dc4c414357c5a6183d263205687c1ba3b481f9285a1008aef7647.png

User does not have an authentication session at the Identity Provider

  1. A user visits a web application (a SAML Service Provider).

  2. The web application redirects the user's browser to the SAML Identity Provider via HAProxy Enterprise SAML Component.

  3. HAProxy Enterprise SAML Component and the web application establish a trust relationship by exchanging certificates over HTTPS.

  4. The user signs on, and the Identity Provider validates credentials.

  5. HAProxy Enterprise SAML Component redirects the user's browser back to the web application with a SAML response containing a SAML authentication assertion. The response is sent to the web application's Assertion Consumer Service URL.

Authentication

When a user wants to access a web application:

  1. HAProxy Enterprise SAML Component checks that the user has sent a valid SAML cookie.

  2. The user has sent a valid SAML cookie

    HAProxy Enterprise SAML Component grants access to the web application.

    The user has not sent a valid SAML cookie

    1. The user sends, through their browsers, a SAML AuthnRequest (Authentication Request) to the Identity Provider.

      The AuthnRequest format is specific to the Identity Provider.

    2. The Identity Provider asks the user to authenticate via an authentication portal or any other way (e.g., tokens or 2-factor authentication).

    3. Once the user has successfully authenticated, the Identity Provider sends a SAML Response to the Service Provider via the user's browser.

      The SAML Response is sent in a POST HTTP request.

      It contains authorization and authentication information about the user, such as the user name, the user's email address, or any custom XML attribute, depending on the Service Provider configuration.

    4. HAProxy Enterprise SAML Component analyzes this SAML Response and allows administrators to make specific checks or actions on XML attributes present in the SAML Response, and to take decisions based on the results.

Using web applications

As long as their browsers send a valid, non-expired, SAML cookie (called saml_cookie), users are granted access to web applications.

Every action requested in the on_saml_response category is executed on each subsequent HTTP response unless set_var_once is specified.

Single Logout

When a user wants to log out:

  1. HAProxy Enterprise SAML Component asks the Identity Provider to log out from any application where the user has previously logged in, by sending a LogoutRequest.

    You can customize the Logout Request sent to the Identity Provider via the logout_request_template_filename configuration directive.

  2. The Identity Provider replies to every application and asks them to log the user out, using a Logout Response.

Prerequisites

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

Installing HAProxy Enterprise SAML Component

Install HAProxy Enterprise SAML Component via your package manager.

To install the HAProxy Enterprise SAML Component on Ubuntu 20.04, run:

$ sudo apt install hapee-extras-spoa-saml

See also

Installing HAProxy Enterprise 1.8r2

Next up

SAML Quick Start on Azure