HAProxy Enterprise Documentation 2.5r1

SAML configuration options

Configuration options

The /etc/hapee-extras/saml.ini file configures how HAProxy Enterprise integrates with the SAML identity provider. It supports the following configuration directives.

Option

Description

Type

Default value

idp_login_url

URL of the Web authentication portal of the Identity Provider. On Microsoft Azure, https://login.microsoftonline.com/{{IDP_APP_ID}}/saml2

String

config_version

The version of the configuration file. Maintains compatibility with future versions.

String

idp_logout_url

Single Logout URL: Endpoint which initiates the SAML Logout for all applications.

On Microsoft Azure, https://login.microsoftonline.com/logout.srf.

String

idp_referer_url

HTTP Referer value to check when receiving HTTP data from the Identity Provider. On Microsoft Azure, https://login.microsoftonline.com/

String

app_login_url

URL where the application expects to receive the SAML Response from the Identity Provider. The reply URL is also referred to as the Assertion Consumer Service (ACS)

String

app_logout_url

When the user browses this URL, initiate a LogoutRequest to the Identity Provider.

String

signing_algo

Cryptographic algorithm used to sign the requests we send.

String

idp_public_cert

X509 public cert of the Identity Provider (in base64 form, .pem) used to verify SAML Response Response and Assertion attributes.

String

verify_signature

Verify the signature of incoming SAML requests.

Boolean

0

require_signed_response

Fail if the XML response is not signed.

Boolean

0

require_signed_assertion

Fail if the XML assertion is not signed.

Boolean

0

signing_key

Private key used to sign requests we send.

String

sign_authn_requests

Set to 1 if you want to sign Authn Requests.

Boolean

0

sign_logout_requests

Set to 1 if you want to sign LogoutRequest requests.

Boolean

0

saml_app_backend

Backend name for this application.

String

bk-{{APP_NAME}}

saml_cookie_secure

Set to 1 if you want cookies to be used for HTTPS connections only (not HTTP).

Boolean

0

saml_cookie_samesite

SameSite cookie attribute value.

String

saml_cookie_httponly

HttpOnly cookie attribute value.

Boolean

1

saml_cookie_time_offset

Cookie time offset in seconds (used to build Expires cookie attribute).

Integer

0

saml_cookie_lifetime

Cookie lifetime in seconds (used to build Expires cookie attribute).

Integer

36000

saml_cookie_domain

Domain cookie attribute value.

String

authn_request_template_filename

Authn Request template filename.

String

logout_request_template_filename

LogoutRequest template filename.

String

Actions

In the /etc/hapee-extras/saml.ini file, actions let you validate the schema, set variables, and other tasks.

on_saml_response check_attr

Description

Mandatory argument

Optional argument

Check an arbitrary attribute in a SAML Response.

To store the attribute value in an HAProxy Enterprise variable txn.my_var_name, use XPath= set_var=.

To set per application variables, use set_var=(\{\{APP_NAME}}.my_var_name:code:.

{{APP_NAME}} is replaced with the application name (ie the section name in saml.ini).

The SAML Response validation fails if an attribute is not present, except if you set the optional flag.

None

on_saml_response check_attr entity_id

Description

Mandatory argument

Optional argument

Check that the audience attribute exists.

The specific entity_id value to check.

None

on_saml_response check_attr version

Description

Mandatory argument

Optional argument

Check that SAML protocol version is 2.0.

None

None

on_saml_response check_attr status_code

Description

Mandatory argument

Optional argument

Check the SALMResponse status code.

None

The status to match. Otherwise compare to urn:oasis:names:tc:SAML:2.0:status:Success.

on_saml_response check_attr destination

Description

Mandatory argument

Optional argument

Check that the SAMLResponse Destination value matches this item.

The destination to match.

To match the configured app_login_url, use <APP_LOGIN_URL>.

On Microsoft Azure, it must match the URL Assertion Consumer Service (ACS).

None

on_saml_response check_attr issuer

Description

Mandatory argument

Optional argument

Check the Issuer attribute of the SAMLResponse.

None

The specific issuer value to check.

on_saml_response check_attr issue_instant

Description

Mandatory argument

Optional argument

Check that the IssueInstant attribute exists.

To store it in a variable, use set_var.

To store it in a timestamp variable, use set_var_as_timestamp.

None

None

on_saml_response check_attr assertion

Description

Mandatory argument

Optional argument

Check that the Assertion attribute exists.

None

None

on_saml_response check_schema

Description

Mandatory argument

Optional argument

Validate the SAML response against the SAML 2.0 xsd schema.

None

None

on_saml_response check_conditions

Description

Mandatory argument

Optional argument

Check the XML attribute, including NotBefore and NotOnOrAfter values.

None

None

on_saml_response check_subject_confirmation_data

Description

Mandatory argument

Optional argument

Check the XML attribute, including NotBefore and NotOnOrAfter values.

None

None

on_logout_request check_attr

Description

Mandatory argument

Optional argument

Check an arbitrary attribute in a LogoutRequest.

To put it in an HAProxy Enterprise variable, use XPath= set_var=.

None

None

on_logout_request check_attr issuer

Description

Mandatory argument

Optional argument

Check the issuer attribute of the LogoutRequest.

None

The specific issuer value to check.

on_logout_request check_attr name_id

Description

Mandatory argument

Optional argument

Check that the nameId attribute exists in the LogoutRequest.

None

None

on_logout_request check_attr destination

Description

Mandatory argument

Optional argument

Check that the LogoutRequest Destination value matches this item.

The destination to match.

To match the configured app_logout_url, use <APP_LOGOUT_URL>.

None

Action flags

Actions accept the following arguments.

Description

Mandatory argument

Optional

This argument is not required.

required

This argument is mandatory.

nofail

For testing purposes. This action never fails, even if it returns an error.

required_count=<count>

Fail if the number of searched elements is different from <count>.

xpath=<XPath expression>

XPath expression to look for. Use with check_attr actions.

expected=<expected_value>

Fail if the result is different from this expression.

set_var=<var_name>

When one or more XPath results are found, store its value in this specific variable. The variable name is prefixed with the application name, then with a dot.

set_var_once

The variable is set only after the POST from the SAML Identity Provider. Otherwise, it is set each time we see the cookie again.

set_var_cnt

The number of XPath results is stored in the variable <APP_NAME>.<VAR_NAME>_cnt.

set_var_as_timestamp

When used with a value in ISO 8601 date and time format (for instance 2020-01-28T15:25:14.884Z), the variable is converted to a timestamp.

set_var_sep=<separator>

When multiple results are returned from the XPath query, separate them with this character.

set_var_default=<default_value>

Default value used if the XPath expression does not match.


Next up

Response Policies
HAProxyConf 2022 - Call for papers