HTTP listener

HTTP listener reference and configuration shared across Fortified ID products.

HTTP listeners can be configured on server level to avoid duplication of configuration on application/module level. Using server level HTTP configuration eliminates the need for globals/expansions to maintain a consistent HTTP listener configuration.

When using HTTP listener configuration, listeners are configured and started when the server starts, not inline when requested by modules. The only configuration needed by modules is to specify the name of listener.

HTTP may also be disabled on server level causing all HTTP listener operations to fail. Use this only for configurations where inbound HTTP is not used/wanted.

Properties
Example

Name	Description	Default
`enabled`	Flag to disable http	`true`
`listeners`	List of HTTP listener objects. If non existing or empty, no listeners will be created (but may be created modules using inline configuration).	`[]`

{
    "server": {
        "http": {
            "enabled": true,
            "listeners": [
                {
                    "name": "default_8080",
                    "host": "0.0.0.0",
                    "port": 8080,
                    "ssl": {
                        "enabled": false
                    }
                }
            ]
        }
    }
}

Listener configuration

A listener represents a combination of host/ip and a port on the local machine. A listener can be used by one or more modules. Listener settings can not be changed or overridden by modules. If a module uses local HTTP configuration that equals an already existing listener, that listener will be used.

Properties
Example

Name	Description	Default
`name`	Logical name of listener
`host`	Host or IP to use	`"0.0.0.0"`
`port`	Port to use	`8080`
`ssl`	SSL/TLS configuration
`options`	Advanced listener options
`redirect_url`	Redirect here from context root	URL
`allow_forward_headers`	NONE, FORWARD, X_FORWARD, ALL	X_FORWARD
`fingerprint`	HTTP fingerprint configuration

{
    "name": "default_8080",
    "host": "0.0.0.0",
    "port": 8080,
    "ssl": {
        "enabled": false
    },
    "redirect_url": "https://www.fortifiedid.se/",
    "allow_forward_headers": "NONE"
}

Name	Description	Default
`enabled`	Flag to enable SSL	`false`
`keystore`	Key store object.
`key_alias`	Alias specifying which key (in the key store) to use.
`key_password`	The key password
`use_alpn`	Flag to turn off ALPN and HTTP/2 support	`true`
`truststore`	Keystore object containing trusted entities.
`client_auth`	Flag to turn on SSL clientAuth. When enabled, all clients must present a valid certificate issued by a valid and trusted issuer available in the configured trust store.	`false`

{
    "ssl": {
        "enabled": true,
        "keystore": {
            "path": "/path/to/keystore.jks",
            "type": "JKS",
            "password": "secret"
        },
        "key_alias": "server",
        "key_password": "secret"
    }
}

ALPN and HTTP/2

ALPN (Application Layer Protocol Negotiation) is a TLS extension that negotiates the protocol before the client and the server start to exchange data. If APLN is enabled, the current listener uses SSL/TLS and if the client supports it, HTTP/2 (h2) will be used.

Advanced configuration

For advanced HTTP listener configuration the options object is used.

When a property in options matches a HttpServerOptions field, it will override the default Vert.x configuration value.

For more information, see VertX documentation.

HTTP Fingerprinting

Controls HTTP User-Agent fingerprinting at the listener level (can also be configured per module). Fingerprinting tracks the browser used to access the listener. If browser properties change during a session, the session will be terminated and, if the user is logged in, they will be logged out. This mechanism helps protect against session hijacking.

Fingerprinting can only be used in combination with sessions.

Properties
Example

Name	Description
`enabled`	Flag to enable fingerprinting (`true/``false`)
`allow_client`	Flag to allow browser generated fingerprints like FingerprintJS (`true/``false`)
`pattern`	Validation pattern (regex) for browser generated fingerprints. Default pattern validates that the fingerprint value is at least 16 chars long. (`".{16,}"`).
`failure_location`	Redirect location used when fingerprint matching fails.

{
    "fingerprint": {
        "enabled": true,
        "allow_client": false,
        "pattern": ".{32,32}",
        "failure_location": "/app/authn/login"
    }
}