Chapter 3. Securing the Undertow HTTP Server

The org.ops4j.pax.web.config.file option refers to undertow.xml or any file with .xml extension. The referenced file is used to configure advanced aspects of the Undertow embedded server.

Fuse Karaf embeds Undertow.

The pax-web-undertow reuses XML Schemas from RHEL and the Undertow subsystem. The pax-web does not use RHEL classes for parsing and processing the XML configuration files, so all the options are valid.

The supported configuration elements are described as follows:

---
<?xml version="1.0" encoding="UTF-8"?>

<!-- Copyright 2005-2018 Red Hat, Inc. Red Hat licenses this file to you under the Apache License, version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

-→

<undertow xmlns="urn:org.ops4j.pax.web:undertow:1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:w="urn:jboss:domain:5.0"

xsi:schemaLocation="

urn:jboss:domain:undertow:4.0 http://www.jboss.org/schema/jbossas/wildfly-undertow_4_0.xsd

urn:jboss:domain:5.0 http://www.jboss.org/schema/jbossas/wildfly-config_5_0.xsd">

<!-- https://docs.jboss.org/author/display/WFLY/Undertow+subsystem+configuration -->

<subsystem xmlns="urn:jboss:domain:undertow:4.0">

<!-- org.wildfly.extension.undertow.BufferCacheDefinition -->

<buffer-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10" />

<server name="default-server">

<!-- HTTP(S) Listener references Socket Binding (and indirectly - Interfaces) -->

<http-listener name="http" socket-binding="http" />

<!-- verify-client: org.xnio.SslClientAuthMode.NOT_REQUESTED, org.xnio.SslClientAuthMode.REQUESTED, org.xnio.SslClientAuthMode.REQUIRED -->

<!--<https-listener name="https" socket-binding="https"-->

<!--security-realm="https" verify-client="NOT_REQUESTED" />-->

<host name="default-host" alias="localhost">

<location name="/" handler="welcome-content" />

<!--<location name="/docs" handler="docs-content" />-->

<access-log directory="${karaf.data}/log" pattern="common" prefix="access_log." suffix="log" rotate="true" />

<filter-ref name="server-header" />

<filter-ref name="x-powered-by-header" />

</host>

</server>

<servlet-container name="default">

<jsp-config />

<websockets />

<welcome-files>

<welcome-file name="index.html" />

<welcome-file name="index.txt" />

</welcome-files>

</servlet-container>

<handlers>

<file name="welcome-content" path="${karaf.home}/welcome-content" />

<!--<file name="docs-content" path="${karaf.home}/docs" />-->

</handlers>

<filters>

<!-- filters for reference from /host/filter-ref and /host/location/filter-ref -->

<response-header name="server-header" header-name="Server" header-value="Pax-HTTP-Undertow" />

<response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Open Source" />

</filters>

</subsystem>

<!-- https://docs.jboss.org/author/display/WFLY/Security+Realms -->

<!--

we'll use "default" security realm by default to configure jaas/properties authentication

(io.undertow.security.idm.IdentityManager):

</undertow>

The various options available to configure Undertow are explained as follows:

Networking options

Basic networking configuration requires two elements:

Undertow server listener configuration

The address or port options allows configuration for http(s) listener in an Undertow embedded server.

`<subsystem>/<server>/<http[s]-listener>` configures the embedded server to listen on the given address/port.

For <https-listener> you can use realm to point to the security configuration and verify-client attribute with one of these values: NOT_REQUESTED, REQUESTED, REQUIRED.

Security configuration

The XML configuration can specify multiple <security-realm name="name"> elements.

The special <security-realm name="default"> realm is used to configure io.undertow.security.idm.IdentityManager.

When the security realm has a different name it can be referenced from the <subsystem>/<server>/<https-listener> element to define additional TLS configuration:

HTTP server configuration

After the configuration of the networking elements the <subsystem>/<server> is used to create actual instance of embedded Undertow server.

Filter and Handler configuration

Filters and handlers handle HTTP requests. Filters pass the request further down the chain and the handlers are actual endpoints that do something, for example servlets.

Filters:

Handlers:

Servlet container configuration

The servlet container defines how Undertow handles servlets.