> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/modules/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/modules/configuration.md).

# Configuration

Configure module deployment and the listener, context, session, and security settings shared by HTTP modules.

Use this reference to configure module deployment and the settings shared by modules that expose HTTP endpoints. Module-specific settings remain in each module's own reference.

## Basic configuration

These configuration properties are common to all modules:

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>name</code></td><td>Canonical module name or alias.</td><td><code>""</code></td><td>true</td></tr><tr><td><code>enabled</code></td><td>Controls whether the module is deployed.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>instances</code></td><td>Number of instances to deploy with the same configuration.</td><td><code>1</code></td><td>false</td></tr><tr><td><code>worker</code></td><td>Deploys the instances with worker execution when enabled.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>group</code></td><td>Deployment group. A configured or built-in module affiliation takes precedence over the fallback.</td><td>Module affiliation or <code>"default"</code></td><td>false</td></tr><tr><td><code>config</code></td><td>Module-specific configuration object.</td><td><code>{}</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "name": "Resource",
  "enabled": true,
  "instances": 1,
  "worker": false,
  "group": "resource-group",
  "config": {
    "context_path": "/files",
    "webroot_dir": "/path/to/dir"
  }
}
```

{% endtab %}
{% endtabs %}

## HTTP configuration

HTTP modules register their routes below an `http_context` and use either a named server-level listener or local compatibility settings. Prefer a named listener so host, port, TLS, and proxy-header handling are configured once.

### Key concepts

#### Context

Every HTTP module registers a context path through `http_context`. The selected listener supplies the network host, port, and TLS settings, while the module defines the routes below its context.

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

```
http://192.168.1.23:8080/path/to/api/operation
 ^      ^            ^   ^           ^ 
 |      |            |   |           |
 |      + host       |   |           |
 + scheme            |   + context   |
                     + port          + endpoint
```

{% endtab %}
{% endtabs %}

The following rules apply to the context property:

1. It must start with `/`.
2. It must not end with `/`.
3. It can contain multiple levels separated by `/`.
4. It can overlap another module's context when their registered routes do not conflict.

#### Keystores

TLS listeners can use a keystore for their private key and certificate and a truststore for certificates they trust.

Two types of key-/truststores are supported:

* Java KeyStore format (`"JKS"`)
* PKCS#12 (`"PKCS12"`)

Key-/truststores can be configured in two ways:

* As a keystore object (recommended)
* Using local properties (deprecated, used only for compatibility)

The configuration can contain the object inline or reference an externalized object with an expansion expression. Externalization allows the same keystore object to be reused.

#### Keystore object

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>data</code></td><td>Base64-encoded keystore data. Required unless <code>path</code> is used.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>path</code></td><td>Path from which the keystore is loaded. Required unless <code>data</code> is used.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>password</code></td><td>Keystore password.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>type</code></td><td>Keystore type.</td><td><code>"PKCS12"</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example (externalized)" %}
Example of an externalized keystore object:

```json
{
  "keystores": {
    "keystore01": {
      "path": "/path/to/keystore.jks",
      "password": "secret",
      "type": "JKS"
    }
  },
  "modules": [
    {
      "name": "ModuleUsingExternalKeystore",
      "config" : {
        "http_keystore": "${keystores.keystore01}"
      }
    }
  ]
}
```

{% endtab %}

{% tab title="Example (inline)" %}
Example of an inline keystore object:

```json
{
  "name": "ModuleWithInlineKeystore",
  "config": {
    "keystore": {
      "data": "YmFu...YW4K",
      "password": "secret",
      "type": "PKCS12"
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Properties

{% hint style="info" %}
Configure transport properties with a server-level [HTTP listener](https://docs.fortifiedid.se/common/server/http-listener) whenever possible.

This recommendation applies to the following settings:

* Host and port
* TLS, including keystore, truststore, client authentication, and ALPN settings
  {% endhint %}

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>http_listener</code></td><td>Name of HTTP listener to use. If not specified, local properties will be used.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_host</code></td><td>Hostname or IP address for the local compatibility listener. *</td><td><code>"0.0.0.0"</code></td><td>false</td></tr><tr><td><code>http_port</code></td><td>Port of HTTP listener. *</td><td><code>8080</code></td><td>false</td></tr><tr><td><code>http_options</code></td><td>Additional Vert.x HTTP server options for the local compatibility listener.</td><td><code>{}</code></td><td>false</td></tr><tr><td><code>http_context</code></td><td>Module context path. All routes registered by a module are relative to this context.</td><td>Module-specific</td><td>false</td></tr><tr><td><code>http_allow_forward_headers</code></td><td>Reverse-proxy header policy: <code>"NONE"</code>, <code>"FORWARD"</code>, <code>"X_FORWARD"</code>, or <code>"ALL"</code>.</td><td><code>"X_FORWARD"</code></td><td>false</td></tr><tr><td><code>http_redirect_url</code></td><td>Optional target for redirecting requests to the listener root.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_use_ssl</code></td><td>Enables TLS for the local compatibility listener. Requires a configured keystore. *</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_use_alpn</code></td><td>Flag to enable support for ALPN (Application Layer Protocol Negotiation), required for using HTTP/2 over SSL/TLS. *</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_keystore</code></td><td>Keystore object. The compatibility alias is <code>http_keystore_ref</code>. *</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_keystore_path</code></td><td>Path to the keystore. *</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_keystore_password</code></td><td>Keystore password. **</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_keystore_type</code></td><td>Keystore type. **</td><td><code>"PKCS12"</code></td><td>false</td></tr><tr><td><code>http_key_alias</code></td><td>Keystore key alias. *</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_key_password</code></td><td>Private-key password. *</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_truststore</code></td><td>Truststore object. The compatibility alias is <code>http_truststore_ref</code>. *</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_truststore_path</code></td><td>Path to the truststore. **</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_truststore_password</code></td><td>Truststore password. **</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_client_auth</code></td><td>Enables TLS client-certificate authentication. *</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_form_attr_limit</code></td><td>Compatibility setting for the maximum size of HTTP form attributes in bytes.</td><td><code>524288</code></td><td>false</td></tr><tr><td><code>http_request_body_limit</code></td><td>Compatibility setting for the maximum HTTP request-body size in bytes.</td><td><code>2097152</code></td><td>false</td></tr><tr><td><code>http_webroot_dir</code></td><td>Compatibility setting for the directory from which static files are served.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_overlay_dir</code></td><td>Compatibility setting for a static web-root overlay directory.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>http_index</code></td><td>Compatibility setting for the index page served when a URL does not name a file.</td><td><code>"index.html"</code></td><td>false</td></tr><tr><td><code>http_session_cookie_path</code></td><td>Cookie path. When omitted, the module context path is used.</td><td>Module context path</td><td>false</td></tr><tr><td><code>http_session_cookie_name</code></td><td>Session cookie name.</td><td><code>"__session"</code></td><td>false</td></tr><tr><td><code>http_session_timeout_ms</code></td><td>Session timeout in milliseconds.</td><td><code>1800000</code></td><td>false</td></tr><tr><td><code>http_session_enabled</code></td><td>Enables the HTTP session handler for the context. The compatibility name is <code>use_session</code>.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_session_cookie_http_only</code></td><td>Prevents browser scripts from reading the session cookie. The legacy compatibility name is <code>http_session_cookie_httponly</code>.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_session_cookie_secure</code></td><td>Session cookie secure flag. Secure cookies are only sent over secure (HTTPS) connections.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_session_cookie_same_site</code></td><td>Session cookie SameSite policy: <code>"STRICT"</code>, <code>"LAX"</code>, or <code>"NONE"</code>.</td><td><code>"NONE"</code></td><td>false</td></tr><tr><td><code>http_headers</code></td><td>Response headers added to routes in the HTTP context.</td><td><code>{}</code></td><td>false</td></tr><tr><td><code>public</code></td><td>Allows requests without an authenticated session.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_auth_redirect_url</code></td><td>Redirect location used when authentication is required.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>use_body_handler</code></td><td>Enables request-body handling for the context.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_enable_file_upload</code></td><td>Compatibility setting that enables file uploads.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_file_upload_dir</code></td><td>Compatibility setting for the upload directory.</td><td><code>"uploads"</code></td><td>false</td></tr><tr><td><code>http_file_upload_delete_files_on_end</code></td><td>Deletes uploaded temporary files when the request ends.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_cors</code></td><td>CORS configuration object.</td><td><code>{"enabled": true}</code></td><td>false</td></tr><tr><td><code>http_cors.enabled</code></td><td>Enables CORS handling.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>http_cors.origins</code></td><td>Array of allowed origins in the form <code>&#x3C;scheme>://&#x3C;host>[:&#x3C;port>]</code>.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>http_cors.allowed_methods</code></td><td>Array of allowed HTTP methods.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>http_cors.allowed_headers</code></td><td>Array of allowed request headers.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>http_cors.exposed_headers</code></td><td>Array of response headers exposed to browsers.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>http_cors.allow_credentials</code></td><td>Allows credentials in cross-origin requests. Explicit origins are required when this is enabled.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_cors.allow_private_network</code></td><td>Allows cross-origin access from public networks to private networks.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_cors.max_age_secs</code></td><td>Browser cache lifetime for CORS preflight responses.</td><td>Handler default</td><td>false</td></tr><tr><td><code>http_csrf</code></td><td>CSRF handler configuration.</td><td><code>{"enabled": true}</code></td><td>false</td></tr><tr><td><code>http_csp</code></td><td>Content Security Policy configuration.</td><td><code>{"enabled": false}</code></td><td>false</td></tr><tr><td><code>http_fingerprint</code></td><td>Session fingerprint configuration object.</td><td><code>{"enabled": false}</code></td><td>false</td></tr><tr><td><code>http_fingerprint.enabled</code></td><td>Enables session fingerprint validation.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_fingerprint.allow_client</code></td><td>Allows a client-supplied fingerprint.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>http_fingerprint.pattern</code></td><td>Regular expression that validates the fingerprint value.</td><td><code>".{16,}"</code></td><td>false</td></tr><tr><td><code>http_fingerprint.failure_location</code></td><td>Redirect location used when fingerprint validation fails.</td><td><code>""</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "http_listener": "default",
  "http_context": "/example",
  "http_session_enabled": true,
  "http_cors": {
    "enabled": true,
    "origins": ["https://app.example.com"]
  }
}
```

{% endtab %}
{% endtabs %}

\*) Use a server-level HTTP listener instead of local transport properties when possible.

\*\*) Used only with key- or truststore path configuration in compatibility modules.