SAML Broker

To learn more about how Fortified ID Access supports SAML, please click LINK.

Overview

This authenticator acts as a SAML Broker (sometimes also referred to as an IdP proxy).

Typically used in SAML brokering scenarios when one or more methods of identification reside on a remote IdP.
Note. Fortified ID Access has native authenticators for some remote IdPs, for example Swedish BankID and Freja. However, if you use BankID or Freja through a third-party provider, you need to configure them using a SAML Broker.

Configuration

Note

Authenticator type: SAMLSPBroker

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
issue_as_sp_entity	When sending authentication request, what is the entity id used.	N/A	true
target_idp_entity	The remote IDP entity id to trust.	N/A	true
custom_identifier	Custom identifier to be set in the event logging entry	N/A	false
force_auth_request	Should the auth request force re-authentication	false	false
assertion_consumer_service_url	Optional override for the outgoing AuthnRequest's AssertionConsumerServiceURL. If omitted or empty, use the first ACS URL in the internal SP metadata. The target IdP must accept this URL.		false
sign_authn_request	Optional boolean controlling AuthnRequest signing. true always signs; false sends unsigned requests. If omitted, follow the target IdP metadata's WantAuthnRequestsSigned setting.		false
sign_algorithm	Which signature algorithm to use if signing authn-requests. Ensure it is working with the private key used. Used whenever the broker signs an AuthnRequest, whether required by IdP metadata or enabled explicitly.	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256	false
sign_digest_method	Which digest method to use if signing authn-requests. Ensure it is working with the selected signature algorithm. Used whenever the broker signs an AuthnRequest, whether required by IdP metadata or enabled explicitly.	http://www.w3.org/2001/04/xmlenc#sha256	false
validate_audience_restrictions	Optional validation rule (true/false)	false	false
validate_destination	Optional validation rule (true/false)	false	false
validate_authn_instant	Optional validation rule (true/false)	false	false
validate_session_timestamp	Optional validation rule (true/false)	false	false
skew_time_seconds	Maximum acceptable time difference (seconds)	60	false
authn_context_class_ref	Value sent in AuthnContextClassRef	N/A	false
replay_max_node_clock_offset_seconds	Maximum pairwise node clock difference used to retain replay markers. All nodes sharing the SP must use the same value and clock skew.	60	false
allowed_authn_context_class_ref	When requesting authn_context_class_ref, comparison is done with exact match. Use this parameter to allow other return values. Configure as array: "allowed_authn_context_class_ref":["xxx","yyy"]	N/A	false

Example

{
    "id": "sp",
    "type": "SAMLSPBroker",
    "config": {
        "base_path": "/saml/authn",
        "issue_as_sp_entity":"https://your_sp_entity",
        "target_idp_entity":"https://your_target_idp_entity"
    }
}

Assertion consumer service URL

Set assertion_consumer_service_url in the broker configuration to override the AssertionConsumerServiceURL in outgoing AuthnRequests. If omitted or empty, the broker uses the first AssertionConsumerService URL in the internal SP metadata.

The override does not modify SP metadata or the ProtocolBinding, which still comes from the first ACS entry. Incoming HTTP request parameters cannot override this configuration. The URL is set before signing, so a signed AuthnRequest protects the selected URL.

When validate_destination is enabled, the configured override is accepted as an additional response destination alongside the ACS URLs from SP metadata. Other destinations are still rejected. Omitting the override keeps the existing metadata-based destination validation.

The receiving IdP must accept the selected URL; otherwise it may reject the request. Configure only a trusted endpoint intended to receive the SAML response.

AuthnRequest signing

sign_authn_request takes precedence over the target IdP metadata:

Configuration	Outbound AuthnRequest
true	Always signed, regardless of WantAuthnRequestsSigned.
false	Always unsigned, even when WantAuthnRequestsSigned is enabled.
Omitted	Signed when the target IdP metadata enables WantAuthnRequestsSigned; otherwise unsigned. This preserves existing behavior.

Signing uses the internal SP's signing certificate and private key, together with sign_algorithm and sign_digest_method. If signing is required but the certificate or private key is missing, request generation fails with a clear error. It does not fall back to an unsigned request.

Caution

Setting sign_authn_request to false disables request signing even if the IdP requires it. The IdP may reject the unsigned request.

Validation

Authentication must start at the broker. The pending request binds the selected IdP, request ID and receiving ACS; unsolicited IdP-initiated login responses are rejected.

The response and assertion issuers must exactly match the selected IdP, with absent or entity issuer format. A trusted signature must protect the assertion, on the response or the assertion itself. If both are signed, both signatures are verified. Encrypted assertions are decrypted before validation.

A bearer SubjectConfirmation must match the receiving ACS and pending request ID, contain an unexpired NotOnOrAfter, and omit NotBefore. A signed response must also match the request ID in its own InResponseTo. Successful response status, response issue time and assertion validity timestamps are checked. Request correlation is mandatory; the former validate_in_response_to setting cannot disable it.

validate_destination, validate_audience_restrictions, validate_authn_instant and validate_session_timestamp enable additional checks. The broker validates returned authentication context against the requested and allowed values before recording replay state or exporting attributes. With validate_authn_instant: true, the broker retains the legacy exclusive age limit of skew_time_seconds and rejects timestamps beyond the allowed future skew. The broker does not read the AuthN SAMLSP module's max_authn_age_seconds property.

Replay protection

The validated issuer and assertion ID are registered atomically before authentication and session exports. Reuse or replay-store failure rejects login. Nodes in the same Vert.x cluster sharing the SP entity ID share replay protection; unclustered instances have independent local state. Retention covers bearer validity plus clock skew and replay_max_node_clock_offset_seconds; cache_ttl_seconds no longer controls it.

Keep node clocks within the configured pairwise offset bound and use identical skew and offset values on all nodes sharing the SP. Changing this policy requires a coordinated restart clearing replay state and pending sessions. Replay state is not guaranteed to survive a complete cluster restart. Restart pending logins created before upgrading to request-bound validation.

Logging

On request sent to remote IDP:

• WEB_100027("Sent auth request to remote IDP")
• IDENTIFIER (user traceid)
• SOURCE_SERVICE_NAME (entity id from requesting SP)
• SOURCE_ADDRESS (user IP address)
• AUTHENTICATOR_ID, Configured id and display_anme
• CUSTOMER_IDENTIFIER (if configured)

On a successful authentication event is logged containing the following:

• WEB_100014("Authenticated using SP-broker method")
• IDENTIFIER (user traceid)
• SOURCE_SERVICE_NAME (entity id from the SAML response)
• SOURCE_USER_NAME (name id from the issued assertion)
• SOURCE_ADDRESS (user IP address)
• AUTHENTICATOR_ID, Configured id and display_anme
• CUSTOMER_IDENTIFIER (if configured)
• All attributes in the incoming assertion with value(s). Multivalued attributes att joined using comma ",".

On a failed response from remote IDP

• WEB_100026("Authenticated failed using SP-broker method")
• IDENTIFIER (user traceid)
• SOURCE_SERVICE_NAME (entity id from the SAML response)
• SOURCE_ADDRESS (user IP address)
• AUTHENTICATOR_ID, Configured id and display_anme
• CUSTOMER_IDENTIFIER (if configured)

SAML response requirements

When consuming and validating the response only one assertion is allowed. Either response or assertion must be signed. No signatures will produce error.

Caution

Currently, only POST binding is supported for outbound and incoming request/response.

Data exposed to global state

After successful validation, data stored in the global state are:

• nameID - containing the name-id reported in the assertion.
• remoteIssuer - value of the IDP entityID issuing the assertion.
• All additional attributes from the assertion. Multivalued attributes are merged into a comma-separated string. FriendlyName is favoured over Name.
  • if an incoming attribute with Name urn:oid:2.5.4.42 and FriendlyName givenName, givenName is used as key in global state.
  • If no FriendlyNAme attribute is present Name is used.