Page tree

Previous Stable Release

Please note that the V3 release branch is now the previous stable release, with the current stable releases from the V4 branch.
Support for V3 will end on Dec 31, 2020.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Using Jetty 9.2

Within this documentation, idp.home will be used to refer to IdP installation directory (as specified during the installation process). JETTY_HOME will be used to refer to the location of the Jetty installation.

TODO: revise these docs to reflect use of JETTY_BASE

Version Notes

There are no known issues with any specific Jetty 9.2 release. The latest stable version should be used.

Required Configuration

  • Jetty listens on ports 8080 and 8443 for user-facing web traffic by default. You will most likely need to modify these ports to 80 and 443 in the jetty.xml and jetty-ssl.xml config files, and make arrangements for Jetty to run as root, utilize the setuid extension to support the privileged ports, use a port forwarding approach, etc.
  • Add the following Java options to JETTY_HOME/start.ini:
    • If you chose to install to a location other than the default (/opt/shibboleth-idp):
      • -Didp.home=<location> (replacing <location> with your install location)
    • -Xmx512m - the maximum amount of memory that Jetty may use, at least 512M is recommended
    • -XX:MaxPermSize=128m - the maximum amount of memory allowed for the permanent generation object space
  • Uncomment --exec
  • Uncomment etc/jetty-ssl.xml at the bottom of JETTY_HOME/start.ini
  • Make sure at least the following modules are enabled in JETTY_HOME/start.ini: plus, servlets, annotations, jstl

Recommended Configuration

  • 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_HOME/tmp, and set in JETTY_HOME/start.ini
  • The Jetty distribution ships with a number of example applications located in the JETTY_HOME/webapps directory and deployment descriptors located in JETTY_HOME/contexts. You should remove all of these unless you are specifically using them.

  • You should also look into locking down the TLS configuration in light of the attacks discovered in the last few years, such as disabling SSLv3 (and possibly even TLS 1.0), and limiting the supported cipher suites. A plausible choice is to copy from the example configuration below for the back-channel SOAP connector.


A recommended logging approach is to use logback for Jetty debug and access logging, because it's the same logging library used by the IdP. Doing this requires configuring Jetty to use the slf4j logging API, which is also used by the IdP. You can use this approach to plug in other slf4j-compatible logging implementations, but the example below uses logback.

  1. Install the necessary logging libraries into JETTY_HOME/lib/logging (the subdirectory helps keep these jars separate from any others).
    1. From the slf4j distribution, copy in slf4j-api-version.jar
    2. From the logback distribution, copy in logback-classic-version.jar, logback-core-version.jar, and logback-access-version.jar
  2. Creating the directory JETTY_HOME/resources if necessary, create two logback configuration files in it for debug and access logging (below are merely examples):

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration scan="true">
        <appender name="jetty" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <Pattern>%date{HH:mm:ss.SSS} - %level [%logger:%line] - %msg%n</Pattern>
        <root level="INFO">
            <appender-ref ref="jetty" />
        <logger name="org.springframework" level="OFF" />
        <logger name="ch.qos.logback" level="WARN" />
      <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />  
      <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <appender-ref ref="FILE" />
  3. Activate the logging and requestlog modules in JETTY_HOME/start.ini
  4. Configure access logging in Jetty by creating JETTY_HOME/etc/jetty-requestlog.xml:

    <?xml version="1.0"?>
    <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "">
    <!-- =============================================================== -->
    <!-- Configure the Jetty Request Log                                 -->
    <!-- =============================================================== -->
    <Configure id="Server" class="org.eclipse.jetty.server.Server">
      <!-- =========================================================== -->
      <!-- Configure Request Log -->
      <!-- =========================================================== -->
      <Ref refid="Handlers">
        <Call name="addHandler">
            <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler">
              <Set name="requestLog">
                <New id="RequestLogImpl" class="ch.qos.logback.access.jetty.RequestLogImpl">
                  <Set name="fileName"><Property name="jetty.base" default="." />/resources/logback-access.xml</Set>

Supporting SOAP Endpoints

The use of the back-channel is discussed in the SecurityAndNetworking topic, and you should review that to understand whether or not you need to support this feature.

If you do need this support, these connections generally require special security properties that are not appropriate for user-facing/browser use. Therefore an additional endpoint must be configured.

  1. Copy the jetty9-dta-ssl-1.0.0.jar (asc) plugin to JETTY_HOME/lib/ext
  2. Create the file JETTY_HOME/etc/jetty-shibboleth.xml and place something like the following content in it (this is modeled on defaults provided by Jetty):

    <Configure id="Server" class="org.eclipse.jetty.server.Server">
      <!-- ============================================================= -->
      <!-- Configure a TLS (SSL) Context Factory                         -->
      <!-- This configuration must be used in conjunction with jetty.xml -->
      <!-- and either jetty-https.xml or jetty-spdy.xml (but not both)   -->
      <!-- ============================================================= -->
      <New id="shibContextFactory" class="net.shibboleth.utilities.jetty9.DelegateToApplicationSslContextFactory">
        <Set name="KeyStorePath">idp.home/credentials/idp-backchannel.p12</Set>
        <Set name="KeyStorePassword">PASSWORD</Set>
        <Set name="EndpointIdentificationAlgorithm"></Set>
        <Set name="excludeProtocols">
          <Array type="String">
        <Set name="IncludeCipherSuites">
          <Array type="String">
      <!-- =========================================================== -->
      <!-- Create a TLS specific HttpConfiguration based on the        -->
      <!-- common HttpConfiguration defined in jetty.xml               -->
      <!-- Add a SecureRequestCustomizer to extract certificate and    -->
      <!-- session information                                         -->
      <!-- =========================================================== -->
      <New id="shibHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
        <Arg><Ref refid="httpConfig"/></Arg>
        <Call name="addCustomizer">
          <Arg><New class="org.eclipse.jetty.server.SecureRequestCustomizer"/></Arg>
      <!-- =========================================================== -->
      <!-- Add a HTTPS Connector.                                      -->
      <!-- Configure an o.e.j.server.ServerConnector with connection   -->
      <!-- factories for TLS (aka SSL) and HTTP to provide HTTPS.      -->
      <!-- All accepted TLS connections are wired to a HTTP connection.-->
      <!--                                                             -->
      <!-- Consult the javadoc of o.e.j.server.ServerConnector,        -->
      <!-- o.e.j.server.SslConnectionFactory and                       -->
      <!-- o.e.j.server.HttpConnectionFactory for all configuration    -->
      <!-- that may be set here.                                       -->
      <!-- =========================================================== -->
      <Call id="httpsConnector" name="addConnector">
          <New class="org.eclipse.jetty.server.ServerConnector">
            <Arg name="server"><Ref refid="Server" /></Arg>
              <Arg name="factories">
                <Array type="org.eclipse.jetty.server.ConnectionFactory">
                    <New class="org.eclipse.jetty.server.SslConnectionFactory">
                      <Arg name="next">http/1.1</Arg>
                      <Arg name="sslContextFactory"><Ref refid="shibContextFactory"/></Arg>
                    <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                      <Arg name="config"><Ref refid="shibHttpConfig"/></Arg>
              <Set name="host"><Property name="" /></Set>
              <Set name="port">8443</Set>
              <Set name="idleTimeout"><Property name="https.timeout" default="30000"/></Set>
              <Set name="soLingerTime"><Property name="https.soLingerTime" default="-1"/></Set>
  3. Replace idp.home with the IdP home directory entered during installation.
  4. Replace PASSWORD with the password for the keystore password entered during installation.
  5. Add etc/jetty-shibboleth.xml to JETTY_HOME/start.ini file (towards the bottom of the file you should see other configuration files listed).

Deploying the IdP

In order to deploy the IdP, Jetty must be informed of the location of the IdP warfile.

Create the file JETTY_HOME/webapp/idp.xml and place the following content in it (replace idp.home with your IdP's home directory):

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="war">idp.home/war/idp.war</Set>
  <Set name="contextPath">/idp</Set>
  <Set name="extractWAR">false</Set>
  <Set name="copyWebDir">false</Set>
  <Set name="copyWebInf">true</Set>

Make sure to apply the settings above, or Jetty will be unable to use the packed warfile.e

  • No labels