Using Jetty 12.0

...

Migrating from Jetty 11 (or 10 if making the jump) is a “mostly lateral” process except that the version of logback will be different because of the Servlet API changes in this version. If you use the “recommended” approach of using logback with Jetty, you’ll need get a different set of jars appropriate to that version’s logging module(s) when adding that module.

The most significant difference from a Shibboleth perspective is that we do not have a supported mechanism to convince Jetty to accept client TLS certificate authentication on a secondary port from arbitrary certificates. This is the so-called “back-channel” support that, while very much historical at this point, dates to the very early days of the project. The Shibboleth software (both IdP and SP) are fully capable of operating all profiles over port 443, with so-called “back-channel” use cases generally relying on message signing as a substitute for mutual TLS, which is generally not as easy to deploy nowadays due to proxying and load balancers.

...

1. Use the setuid extension to support listening on the privileged ports as a non-root user. This extension is now JNA-based and is undocumented at this point, and has not yet been tried.

2. Use a port forwarding approach (load balancer, iptables rules, etc).

3. Adjust the range of ports considered privileged if supported by your Linux kernel.

4. Use POSIX capabilities to allow use of priviledged ports by an unpriviledged process, e.g. when using systemd by setting AmbientCapabilities=CAP_NET_BIND_SERVICE 

Example idp.ini

# --------------------------------------- 
# Module: idp
# Shibboleth IdP
# --------------------------------------- 
--module=idp

## Keystore file path (relative to $jetty.base)
jetty.sslContext.keyStorePath=../credentials/idp-userfacing.p12
## Truststore file path (relative to $jetty.base)
jetty.sslContext.trustStorePath=../credentials/idp-userfacing.p12

## Keystore type
jetty.sslContext.keyStoreType=PKCS12
## Truststore type and provider
jetty.sslContext.trustStoreType=PKCS12

## Keystore password
jetty.sslContext.keyStorePassword=changeit
## Truststore password
jetty.sslContext.trustStorePassword=changeit
## KeyManager password
jetty.sslContext.keyManagerPassword=changeit

## Deny SSL renegotiation
jetty.sslContext.renegotiationAllowed=false

## Connector host/address to bind to
# jetty.ssl.host=0.0.0.0

## Connector port to listen on
jetty.ssl.port=443

# Allows use of default IdP command line tools.
jetty.http.host=127.0.0.1
jetty.http.port=80

The TLS credential example relies on a PKCS12 file containing the X.509 certificate and private key used to secure the HTTPS channel that users access during authentication and other browser-based message exchanges involving the IdP. This is generally the one you get from a browser-compatible CA, and the example shows it being loaded from a directory inside the JETTY_BASE tree.

...

$ java -jar /opt/jetty-home-1112.0.0/start.jar --add-module=logging-logback

Jetty will populate a lib/logging folder with the 2 logback libraries it requires. If there are older versions left behind by earlier Jetty versions, you will need to remove them.

...

The next step is to instruct Jetty to produce its access/request log using the same logging APIs it uses for everything else. This is not a Jetty module at this point, so requires the etc/jetty-requestlog.xml file we provide:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">

<!-- =============================================================== -->
<!-- Configure the Jetty Request Log                                 -->
<!-- =============================================================== -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">

  <!-- =========================================================== -->
  <!-- Configure Request Log for Server                            -->
  <!-- Use RequestLogHandler for a context specific RequestLog     -->
  <!-- =========================================================== -->
  <Set name="RequestLog">
    <New id="RequestLog" class="org.eclipse.jetty.server.CustomRequestLog">
      <!-- Writer -->
      <Arg>
        <New class="org.eclipse.jetty.server.Slf4jRequestLogWriter" />
      </Arg>

      <!-- Format String -->
      <Arg>
        <Property name="jetty.requestlog.formatString" deprecated="jetty.customrequestlog.formatString">
          <Default>
            <Get class="org.eclipse.jetty.server.CustomRequestLog" name="EXTENDED_NCSA_FORMAT"/>
          </Default>
        </Property>
      </Arg>
    </New>
  </Set>
</Configure>

A sample logback configuration for both debug and request logging is provided in resources/logback.xml.

...

As noted above, this is no longer something we support via a separate port. You should publish support for SOAP, if you need it, on port 443 in your metadata. The IdP will automatically reject any requests it cannot authenticate using message signatures.

Other Modules

Jetty has a ton of advanced and optional functionality available in the form of modules that can be enabled selectively. They don't function in the way Apache modules do, but they're basically packaged "example" configuration files that will get copied from JETTY_HOME into JETTY_BASE when you need them and you get "just" the minimum files needed to support the feature but keep future upgrades simple.

...

$ cd jetty-base
$ java -jar /opt/jetty-home-1112.0.0/start.jar --add-module=modulename

Supporting

...

X-Forwarded-For Natively

If you are running the Jetty engine behind a proxy or load balancer Jetty has built-in support for forwarding the client address and other details via headers using its http“http-forwarded forwarded” module, and after enabling it as above you can edit the resulting properties file adding it with the --add-module command (see previous section) you can edit the https-forwarded.ini file it will create to configure it.

Note that this example applies the forwarding rule to all ports, so if you also operate the server on other ports, those must also be proxied/protected or this will lead to exposures due to clients having the ability to smuggle in a false client address.

Local Proxying via Apache

If your IdP is behind Apache rather than proxied via a load balancer, you probably might only need it to listen for HTTP traffic locally. This is not applicable in general to load balancing via an applicance like an F5 or NetScaler.

At present, this involves commenting out or removing two lines from the [depend] section of idp.mod: the lines containing https and ssl.

Next, add modules to be loaded in start.d/idp.ini. Alternatively, create your own start.d/http.ini to keep this configuration separate. Add the following to one of these files.

--module=http.

The http-forwarded module mentioned above is also required so that requests coming to the IdP aren't seen as coming from localhost. Follow the instructions above to install this module or, since its defaults are acceptable, just add the following to start.d/idp.ini or start.d/http.ini:--module=http-forwarded

Finally, make sure the jetty.http.host and jetty.http.port properties are set apropriately in idp.ini, or remove them from there and add them to http.ini.

...

Since 8080 is the default http port for Jetty, It's also okay to leave this unset. That change will confine Jetty to listen locally only rather than over a network.