HTTP listener

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.

Which listener a module uses is specified by property http_listener (in the module configuration).

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

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).	[]

Example

{
    "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

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

Example

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

SSL/TLS configuration

Properties

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

Example

{
    "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.

HTTP/2 requires SSL/TLS (h2). Unencrypted HTTP/2 (h2c) is NOT supported.

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

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.

Example

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