Using Jetty 9.3
Note |
---|
The material here is directed at those managing their own container by hand, not those relying on the Windows Installer to install Jetty on their behalf. |
Table of Contents |
---|
The following conventions are used this document:
...
These pages are examples and do not reflect any normative requirements or assumptions on the part of the IdP software and may be a mix of suggestions from both the project team and deployers. You should take any of this advice with a grain of local salt and consider general security/deployment considerations appropriate to the use of web software in your local environment. The official information about containers and versions we support is solely maintained on the SystemRequirements page. If you wish to operate without complete responsibility for your Java servlet container, you may consider the Windows package we provide that includes an embedded container. |
Table of Contents |
---|
The following conventions are used this document:
- /opt/shibboleth-idp is used to indicate that an absolute path to the IdP installation directory is required
idp.home
refers to the IdP installation directory (as specified during the installation process)JETTY_HOME
refers to the location of the Jetty installation (jetty-dist-$VERSION)JETTY_BASE
refers to the directory containing your deployment-specific Jetty configuration files- All paths are relative to
JETTY_BASE
unless otherwise noted
...
- start.ini
- start.d/http.ini
- start.d/https.ini
- start.d/ssl.ini
- etc/jetty-ssl-context.xml
- etc/jetty-requestlog.xml (optional)
- libetc/ext/jetty9-dta-jetty-rewrite.xml (optional)
- lib/ext/jetty9-dta-ssl-1.0.0.jar (optional)
lib/logging/jcl-over-slf4j-1.7.7.jar (optional)
lib/logging/logback-access-1.1.2.jar (optional)
lib/logging/logback-classic-1.1.2.jar (optional)
lib/logging/logback-core-1.1.2.jar (optional)
- lib/logging/slf4j-api-1.7.12.jar (optional)
- resources/logback.xml (optional)
resources/logback-access.xml (optional)
- webapps/idp.xml
- tmp (optional)
...
Code Block | ||||
---|---|---|---|---|
| ||||
# Required Jetty modules
--module=server
--module=deploy
--module=annotations
--module=resources
--module=logging
--module=requestlog
--module=servlets
--module=jsp
--module=jstl
--module=ext
--module=plus
--module=rewrite
# Allows setting Java system properties (-Dname=value)
# and JVM flags (-X, -XX) in this file
# NOTE: spawns child Java process
--exec
# Bypass file validation for the SSL module, to work around a bug in Jetty 9.3.X
--skip-file-validation=ssl
# Uncomment if IdP is installed somewhere other than /opt/shibboleth-idp
#-Didp.home=/path/to/shibboleth-idp
# Alternate garbage collector that reduces memory needed for larger metadata files
-XX:+UseG1GC
# Maximum amount of memory that Jetty may use, at least 1.5G is recommended
# for handling larger (> 25M) metadata files but you will need to test on
# your particular metadata configuration
-Xmx1500m
# Maximum amount of memory allowed for the JVM permanent generation (Java 7 only)
-XX:MaxPermSize=128m
|
...
- From the slf4j distribution, copy in slf4j-api-version.jar
- From the logback distribution, copy in logback-classic-version.jar, logback-core-version.jar, and logback-access-version.jar
Configure Jetty to use logback for request logging by creating JETTY_BASE/etc/jetty-requestlog.xml with the following content:
Code Block language xml title jetty-requestlog.xml collapse true <?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> <!-- =============================================================== --> <!-- Configure the Jetty Request Log --> <!-- =============================================================== --> <Configure id="Server" class="org.eclipse.jetty.server.Server"> <Set name="RequestLog"> <New id="RequestLog" class="ch.qos.logback.access.jetty.RequestLogImpl"> <Set name="fileName"><Property name="jetty.base" default="." />/resources/logback-access.xml</Set> </New> </Set> <Ref refid="RequestLog"> <Call name="start" /> </Ref> </Configure>
Configure logging policy for Jetty internals logging and request logging. Sample logback configuration files are provided for convenience.
Code Block language xml title logback.xml collapse true <?xml version="1.0" encoding="UTF-8"?> <configuration scan="true"> <appender name="jetty" class="ch.qos.logback.core.rolling.RollingFileAppender"> <File>${jetty.base}/logs/jetty.log</File> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>${jetty.base}/logs/jetty-%d{yyyy-MM-dd}.log.gz</FileNamePattern> </rollingPolicy> <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> <charset>UTF-8</charset> <Pattern>%date{HH:mm:ss.SSS} - %level [%logger:%line] - %msg%n</Pattern> </encoder> </appender> <root level="INFO"> <appender-ref ref="jetty" /> </root> <logger name="org.springframework" level="OFF" /> <logger name="ch.qos.logback" level="WARN" /> </configuration>
Code Block language xml title logback-access.xml collapse true <configuration> <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${jetty.base}/logs/access.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${jetty.base}/logs/access.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>${jetty.base}/logs/access-%d{yyyy-MM-dd}.log.gz</fileNamePattern> </rollingPolicy> <encoder>core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>${jetty.base}/logs/access-%d{yyyy-MM-dd}.log.gz</fileNamePattern> </rollingPolicy> <encoder> <pattern>combined</pattern> </encoder> </appender> <appender-ref ref="FILE" /> </configuration>
Temporary Files
Jetty will use /tmp
as a staging area for unpacking the warfile, and if you have cron jobs sweeping that for old files, your IdP can be disrupted. You will probably want to create JETTY_BASE/tmp
, and add the following configuration directive to JETTY_BASE/start.ini:
-Djava.io.tmpdir=tmp
Disable Directory Indexing
Jetty has vulnerabilities related to directory indexing (sigh) so we suggest disabling that feature at this point. There are a few different ways this can be done (see https://webtide.com/indexing-listing-vulnerability-in-jetty/), but one method that's fairly self-contained within the IdP footprint is to modify web.xml (i.e. copy the original version from idp.home/dist/webapp/WEB-INF/web.xml to idp.home/edit-webapp/WEB-INF/web.xml) and then rebuild the war file.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<servlet> <servlet-name>default</servlet-name> <servlet-class>org.eclipse.jetty.servlet.DefaultServlet</servlet-class> <init-param> <param-name>dirAllowed</param-name> |
...
<param-value>false</param-value> </ |
...
init-param> |
...
Temporary Files
Jetty will use /tmp
as a staging area for unpacking the warfile, and if you have cron jobs sweeping that for old files, your IdP can be disrupted. You will probably want to create JETTY_BASE/tmp
, and add the following configuration directive to JETTY_BASE/start.ini:
...
<load-on-startup>0</load-on-startup>
</servlet> |
You can place it above the existing <servlet>
elements in the file.
Optional Configuration
Supporting SOAP Endpoints
...
Jetty can be configured to consume the 'x-forwarded-proto' HTTP header to override the connection protocol originating at the load balancer, instead respecting the protocol being used between the client and the load balancer, communicated in the x-forwarded-proto header. The Proxy / Load Balancer Configuration section of the Jetty documentation provides instruction on the required configuration.
...
Code Block |
---|
RequestHeader set X-Forwarded-Proto "https" env=HTTPS ProxyPass /idp http://localhost:8080/idp connectiontimeout=5 timeout=15 RequestHeader set REMOTE-USER %{REMOTE_USER}s |
Supporting X-Forwarded-For
...
If you are running the Jetty engine behind a proxy or load balancer Jetty 9.3 has built-in support for forwarding the client address and other details via headers.
Warning |
---|
As with any proxied deployment, you MUST take care to lock down the path between the proxy and the Jetty server, and the proxy MUST have support for sanitizing and preventing any client attempt to smuggle and hijack those headers. Failure to do so will result in a variety of security compromises. There are many other considerations to proxying far beyond the scope of this document. |
- Copy the file JETTY_BASE/etc/jetty.xml to JETTY_HOME/etc/jetty.xml
- Edit the file in JETTY_HOME/etc/jetty.xml, locate the:
...
Code Block |
---|
<Set name="outputBufferSize">32768</Set> <Set name="requestHeaderSize">8192</Set> <Set name="responseHeaderSize">8192</Set> <Call name="addCustomizer"> <Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer" /></Arg> </Call> |
Code Block |
---|
<Call name="addCustomizer"> <Arg> <New class="org.eclipse.jetty.server.ForwardedRequestCustomizer" > <Set name="forwardedForHeader">X-MyCustom-Header</Set> </New> </Arg> </Call> |
...