{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Using Jetty 12.0","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"The official information about containers and versions we support is solely maintained on the ","type":"text"},{"text":"SystemRequirements","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199511079"}}]},{"text":" page. If you wish to operate without complete responsibility for your Java servlet container, you may consider the ","type":"text"},{"text":"Windows","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199500769"}}]},{"text":" package we provide that installs a version of Jetty with very limited configurability.","type":"text"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"2"},"maxLevel":{"value":"3"}},"macroMetadata":{"macroId":{"value":"77e16e625ead9814f58e917457f556ca"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"c52d324f-3148-47d3-9696-76fc8ebeed61"}},{"type":"paragraph","content":[{"text":"The following conventions are used this document:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/opt/shibboleth-idp is used to indicate that an absolute path to the IdP installation directory is required","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"idp.home","type":"text","marks":[{"type":"code"}]},{"text":" refers to the IdP installation directory (as specified during the installation process)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JETTY_HOME","type":"text","marks":[{"type":"code"}]},{"text":" refers to the location of the Jetty installation (jetty-home-$VERSION)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":" refers to the directory containing your deployment-specific Jetty configuration files","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All paths are relative to ","type":"text"},{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":" unless otherwise noted","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"We strongly recommend placing all IdP-specific Jetty configuration under ","type":"text"},{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":" to facilitate Jetty upgrades. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" place that directory inside the IdP installation directory; they can be siblings as desired.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that Jetty 12 requires the recommended home/base split; the distribution itself is always considered read-only.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Do NOT skip the Getting Started section. All of the example material depends on the use of files that have to be downloaded and installed to create an initial jetty-base directory tree.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Version Notes","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"latest stable version","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.eclipse.org/jetty/download.html"}}]},{"text":" of Jetty 12 should be used.","type":"text"}]},{"type":"paragraph","content":[{"text":"Migrating from Jetty 11 (or 10 if making the jump) is a “mostly lateral” process ","type":"text"},{"text":"except","type":"text","marks":[{"type":"em"}]},{"text":" 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 get a different set of jars appropriate to that version’s logging module(s) when adding that module.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"If you still rely on a secondary port for some use cases, you should migrate off of that approach prior to upgrading Jetty.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Getting Started","type":"text"}]},{"type":"paragraph","content":[{"text":"The examples on this page are based on the use of a number of files that are not included in the Jetty distribution but are part of the ","type":"text"},{"text":"java-idp-jetty-base","type":"text","marks":[{"type":"link","attrs":{"href":"https://git.shibboleth.net/view/?p=java-idp-jetty-base.git"}}]},{"text":" project we store in our Git repository. The examples won't work as is without starting from that complete set of example files. The ","type":"text"},{"text":"12","type":"text","marks":[{"type":"code"}]},{"text":" branch contains the files used in this material.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following commands (Linux-style) will get you to the starting point assumed from the examples in this page:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ git clone https://git.shibboleth.net/git/java-idp-jetty-base\n$ cd java-idp-jetty-base\n$ git checkout 12\n$ cp -r jetty-impl/src/main/resources/net/shibboleth/idp/module/jetty/jetty-base /my/desired/location/","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Required Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The bulk of the configuration is established by setting properties in \"ini\" files that are combined in the ","type":"text"},{"text":"start.d","type":"text","marks":[{"type":"strong"}]},{"text":" directory. Some of the properties are defined by Jetty and configure built-in modules and others are specific to the IdP and configure the custom module we created.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"start.d/idp.ini","type":"text","marks":[{"type":"em"}]},{"text":" file that configures the “idp” module contains not only the bulk of the basic settings needed but is also a place you can add your own settings to control JVM startup, change which logging module is used, etc. Or you can continue to use a separate ","type":"text"},{"text":"start.ini","type":"text","marks":[{"type":"em"}]},{"text":" file as shown next.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Configure Jetty Modules and JVM Settings","type":"text"}]},{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" start.d/start.ini","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"start.ini","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"# Any other required Jetty modules...\n \n# Allows setting Java system properties (-Dname=value)\n# and JVM flags (-X, -XX) in this file\n# NOTE: spawns child Java process\n--exec\n\n# Uncomment if IdP is installed somewhere other than /opt/shibboleth-idp\n#-Didp.home=/path/to/shibboleth-idp\n\n# Maximum amount of memory that Jetty may use, at least 1.5G is recommended\n# for handling larger (> 25M) metadata files but you will need to test on\n# your particular metadata configuration. If MDQ metadata on demand is used,\n# requirements may be much lower.\n-Xmx1500m\n\n# Prevent blocking for entropy.\n-Djava.security.egd=file:/dev/urandom\n\n# Set Java tmp location\n-Djava.io.tmpdir=tmp\n\n# May be needed in certain cases depending on content of TLS certificate.\n#jetty.ssl.sniHostCheck=false","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Configure HTTP/HTTPS Connectors","type":"text"}]},{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" credentials/idp-userfacing.p12","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"start.d/idp.ini","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"The basic HTTP/HTTPS port, address, etc. configuration can be handled within the custom \"idp\" module and the idp.ini property file.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example below shows some of the basic properties you can use to configure networking and TLS credentials.","type":"text"}]},{"type":"paragraph","content":[{"text":"One challenge remains that if you want to use standard ports on Linux, you would need to pick one of these options to avoid running as root:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the setuid module to support listening on the privileged ports as a non-root user. This extension is now JNA-based and seems to be undocumented at this point, but works fine.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use a port forwarding approach (load balancer, iptables rules, etc).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Adjust the range of ports considered privileged if supported by your Linux kernel.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"POSIX capabilities","type":"text","marks":[{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Capability-based_security#POSIX_capabilities"}}]},{"text":" to allow use of priviledged ports by an unpriviledged process, e.g. when using ","type":"text"},{"text":"systemd","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.freedesktop.org/software/systemd/man/systemd.exec.html#AmbientCapabilities="}}]},{"text":" by setting ","type":"text"},{"text":"AmbientCapabilities=CAP_NET_BIND_SERVICE","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example idp.ini","type":"text","marks":[{"type":"strong"}]}]},{"type":"expand","attrs":{"title":"idp.ini"},"content":[{"type":"codeBlock","content":[{"text":"# --------------------------------------- \n# Module: idp\n# Shibboleth IdP\n# --------------------------------------- \n--module=idp\n\n## Keystore file path (relative to $jetty.base)\njetty.sslContext.keyStorePath=../credentials/idp-userfacing.p12\n## Truststore file path (relative to $jetty.base)\njetty.sslContext.trustStorePath=../credentials/idp-userfacing.p12\n\n## Keystore type\njetty.sslContext.keyStoreType=PKCS12\n## Truststore type and provider\njetty.sslContext.trustStoreType=PKCS12\n\n## Keystore password\njetty.sslContext.keyStorePassword=changeit\n## Truststore password\njetty.sslContext.trustStorePassword=changeit\n## KeyManager password\njetty.sslContext.keyManagerPassword=changeit\n\n## Deny SSL renegotiation\njetty.sslContext.renegotiationAllowed=false\n\n## Connector host/address to bind to\n# jetty.ssl.host=0.0.0.0\n\n## Connector port to listen on\njetty.ssl.port=443\n\n# Allows use of default IdP command line tools.\njetty.http.host=127.0.0.1\njetty.http.port=80","type":"text"}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":" tree.","type":"text"}]},{"type":"paragraph","content":[{"text":"A variety of other networking properties can be set based on the built-in Jetty http and https modules; refer to their documentation.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Configure IdP Context Descriptor","type":"text"}]},{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" webapps/idp.xml","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"In order to deploy the IdP, Jetty must be informed of the location of the IdP war file. This file is called a context descriptor and the recommended content is provided below.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note this file assumes the location of the IdP installation is explicitly set in the file, and controls the context path to which the application is deployed, which is ","type":"text"},{"text":"/idp","type":"text","marks":[{"type":"strong"}]},{"text":" in the following configuration block.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"idp.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\n /opt/shibboleth-idp/war/idp.war\n /idp\n false\n false\n true\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Recommended Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Jetty Logging","type":"text"}]},{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"start.d/idp.ini, resources/logback.xml","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"The recommended approach is to use logback for all Jetty logging. Note that this isn’t required, and the version of logback (or slf4j) used does not depend on the version used by the IdP. They are separately configured and can vary independently.","type":"text"}]},{"type":"paragraph","content":[{"text":"To enable the logback support in Jetty, first add this to ","type":"text"},{"text":"idp.ini","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"--module=logging-logback","type":"text"}]},{"type":"paragraph","content":[{"text":"Then ask Jetty to download the necessary logging libraries by running the ","type":"text"},{"text":"--add-module","type":"text","marks":[{"type":"code"}]},{"text":" command:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ java -jar /opt/jetty-home-12.0.0/start.jar --add-module=logging-logback","type":"text"}]},{"type":"paragraph","content":[{"text":"Jetty will populate a ","type":"text"},{"text":"lib/logging","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Of course, this is completely insecure. If you want to be appropriately careful, you can compare the 2 jars it downloads to the signed copies available from Maven Central and check their signatures.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"If you find that Jetty isn’t producing the logging output expected, you may wish to try adding this to your startup sequence:","type":"text"}]},{"type":"codeBlock","content":[{"text":"-Dlogback.configurationFile=resources/logback.xml","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"etc/jetty-requestlog.xml","type":"text","marks":[{"type":"em"}]},{"text":" file we provide:","type":"text"}]},{"type":"expand","attrs":{"title":"etc/jetty-requestlog.xml"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"A sample logback configuration for both debug and request logging is provided in ","type":"text"},{"text":"resources/logback.xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Disable Directory Indexing","type":"text"}]},{"type":"paragraph","content":[{"text":"Jetty has had 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, but one method that's fairly self-contained within the IdP footprint is to modify ","type":"text"},{"text":"web.xml","type":"text","marks":[{"type":"em"}]},{"text":" (i.e. copy the original version from ","type":"text"},{"text":"idp.home/dist/webapp/WEB-INF/web.xml","type":"text","marks":[{"type":"em"}]},{"text":" to ","type":"text"},{"text":"idp.home/edit-webapp/WEB-INF/web.xml","type":"text","marks":[{"type":"em"}]},{"text":") and then rebuild the war file.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"web.xml addition","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n default\n org.eclipse.jetty.ee9.servlet.DefaultServlet\n \n dirAllowed\n false\n \n 0\n ","type":"text"}]},{"type":"paragraph","content":[{"text":"You can place it above the existing ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements in the file.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"TLS Ciphers","type":"text"}]},{"type":"paragraph","content":[{"text":"As with all web servers, it's a challenge to stay on top of all the best practices related to TLS/SSL versions, ciphers, etc. Jetty has been good of late in shipping reasonable defaults, but they frequently get bad advice pressuring them to be \"more interoperable\", so it's hard to count on things staying good. It's usually best to be in a position to make adjustments to this quickly, and test after upgrades.","type":"text"}]},{"type":"paragraph","content":[{"text":"Jetty documents a way to adjust this sort of thing ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.eclipse.org/jetty/documentation/jetty-12/operations-guide/index.html#og-protocols-ssl-customize-versions"}}]},{"text":". The basic procedure is to create a file at ","type":"text"},{"text":"etc/tls-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" to adjust the settings. You should do some testing against SSL Labs or some other source of information to evaluate what the defaults look like and make any adjustments you think are warranted.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Optional Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supporting SOAP Endpoints","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Other Modules","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"JETTY_HOME","type":"text","marks":[{"type":"code"}]},{"text":" into ","type":"text"},{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":" when you need them and you get \"just\" the minimum files needed to support the feature but keep future upgrades simple.","type":"text"}]},{"type":"paragraph","content":[{"text":"To enable a module, you run the Jetty start file from within ","type":"text"},{"text":"JETTY_BASE","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ cd jetty-base\n$ java -jar /opt/jetty-home-12.0.0/start.jar --add-module=modulename","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supporting X-Forwarded-For Natively","type":"text"}]},{"type":"paragraph","content":[{"text":"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-forwarded” module, and after adding it with the --add-module command (see previous section) you can edit the ","type":"text"},{"text":"https-forwarded.ini ","type":"text","marks":[{"type":"em"}]},{"text":"file it will create to configure it.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Local Proxying via Apache","type":"text"}]},{"type":"paragraph","content":[{"text":"If your IdP is behind Apache rather than proxied via a load balancer, you 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"At present, this involves commenting out or removing two lines from the [depend] section of idp.mod: the lines containing https and ssl.","type":"text"}]},{"type":"paragraph","content":[{"text":"The http-forwarded module mentioned above is also required so that requests coming to the IdP aren't seen as coming from localhost.","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, make sure the ","type":"text"},{"text":"jetty.http.host","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"jetty.http.port","type":"text","marks":[{"type":"strong"}]},{"text":" properties are set apropriately in ","type":"text"},{"text":"idp.ini","type":"text","marks":[{"type":"em"}]},{"text":", or remove them from there and add them to ","type":"text"},{"text":"http.ini","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":"jetty.http.host=127.0.0.1\njetty.http.port=8080","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]}],"version":1}