# 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.

{% hint style="info" %}
Which listener a module uses is specified by property `http_listener` (in the module configuration).
{% endhint %}

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.

{% tabs %}
{% tab title="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). | `[]`    |
| {% endtab %} |                                                                                                                                                |         |

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

## 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.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="268">Name</th><th width="263">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>name</code></td><td>Logical name of listener</td><td></td></tr><tr><td><code>host</code></td><td>Host or IP to use</td><td><code>"0.0.0.0"</code></td></tr><tr><td><code>port</code></td><td>Port to use</td><td><code>8080</code></td></tr><tr><td><code>ssl</code></td><td>SSL/TLS configuration</td><td></td></tr><tr><td><code>options</code></td><td>Advanced listener options</td><td></td></tr><tr><td><code>redirect_url</code></td><td>Redirect here from context root</td><td>URL</td></tr><tr><td><code>allow_forward_headers</code></td><td>NONE, FORWARD, X_FORWARD, ALL</td><td>X_FORWARD</td></tr><tr><td><code>fingerprint</code></td><td>HTTP fingerprint configuration</td><td></td></tr></tbody></table>

{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

### SSL/TLS configuration

{% tabs %}
{% tab title="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` |
| {% endtab %}   |                                                                                                                                                                          |         |

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

### 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.

{% hint style="warning" %}
HTTP/2 requires SSL/TLS (h2). Unencrypted HTTP/2 (h2c) is NOT supported.
{% endhint %}

### 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](https://vertx.io/).

### 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.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="233">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Flag to enable fingerprinting (<code>true/</code><strong><code>false</code></strong>)</td></tr><tr><td><code>allow_client</code></td><td>Flag to allow browser generated fingerprints like FingerprintJS (<code>true/</code><strong><code>false</code></strong>)</td></tr><tr><td><code>pattern</code></td><td>Validation pattern (regex) for browser generated fingerprints. Default pattern validates that the fingerprint value is at least 16 chars long. (<code>".{16,}"</code>).</td></tr><tr><td><code>failure_location</code></td><td>Redirect location used when fingerprint matching fails.</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}