...
| Table of Contents | ||||
|---|---|---|---|---|
|
The following conventions are used this document:
...
| Info |
|---|
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 a project we store in our Git repositorrepository, cloneable from https://git.shibboleth.net/git/java-idp-jetty-base. The examples won't work as is without starting from that complete set of example files. The 9.4.0 branch contains the material used in this material. We may publish it in a more "official" capacity in the future, but for now it's simply an example to build on. It includes some custom Jetty "modules" that help support a simpler configuration and come packaged with logging libraries and other pieces that make the example here much simpler to explain. |
...
The bulk of the configuration is established by setting properties in "ini" files that are combined in the start.d 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 modules we created.
File(s): start.d/start.ini
This is a file you can create to add any specific options you want to use in addition to the defaults, such as enabling additional modules or setting JVM or other system properties.
...
| Code Block | ||
|---|---|---|
| ||
# Any other required Jetty modules...
# Allows setting Java system properties (-Dname=value)
# and JVM flags (-X, -XX) in this file
# NOTE: spawns child Java process
--exec
# Uncomment if IdP is installed somewhere other than /opt/shibboleth-idp
#-Didp.home=/path/to/shibboleth-idp
# Newer 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
# Prevent blocking for entropy.
-Djava.security.egd=file:/dev/urandom
# Set Java tmp location
-Djava.io.tmpdir=tmp
|
Configure HTTP/HTTPS Connectors
File(s): credentials/idp-userfacing.p12, start.d/idp.ini
The basic HTTP/HTTPS port, address, etc. configuration is handled within the custom "idp" module and the idp.ini property file.
The example below shows some of the basic properties you can use to configure networking and TLS credentials.
...
Configure IdP Context Descriptor
File(s): webapps/idp.xml
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.
...
Recommended Configuration
Jetty Logging
File(s):start.d/idp-logging.ini, resources/logback.xml, resources/logback-access.xml
The recommended approach is to use logback for all Jetty logging. The logback and slf4j libraries are needed to support this configuration must be added to JETTY_BASE/lib/logback and JETTY_BASE/lib/slf4j folders respectively.
If you don't want to use this feature, just remove the etc/idp-logging.ini file.
...
Jetty documents a way to adjust this sort of thing here. The basic procedure is to create a file at etc/tweak-ssl.xml to adjust the settings. A starting point to further adjust is shown below.
...
Supporting SOAP Endpoints
File(s): /opt/shibboleth-idp/credentials/idp-backchannel.p12, etc/idp-backchannel.xml, modules/idp-backchannel.mod, start.d/idp-backchannel.ini
...
The jetty94-dta-ssl-1.0.0.jar (asc) plugin can be placed in JETTY_BASE/lib/ext
We provide a backchannel module to control the feature and turn it on or off. Note that because we were forced to update the plugin to accomodate a Jetty change, it has been renamed, the class renamed, and the XML file loaded by the module updated to reflect this change.
Adjust JETTY_BASE/start.d/idp-backchannel.ini as required:
Code Block # --------------------------------------- # Module: idp-backchannel # Shibboleth IdP Dedicated SOAP Connector # --------------------------------------- --module=idp-backchannel ## Backchannel connector port to listen on # idp.backchannel.port=8443 ## Backchannel keystore file path (relative to $jetty.base) # idp.backchannel.keyStorePath=../credentials/idp-backchannel.p12 ## Backchannel keystore password # idp.backchannel.keyStorePassword=changeit ## Backchannel keystore type # idp.backchannel.keyStoreType=PKCS12
Modify JETTY_BASE/etc/idp-backchannel.xml if desired. You get more control over the TLS settings if you need them, but normally this file is just used to plug in the properties we support from the ini file.
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.
...
Supporting X-Forwarded-For Natively
File(s): modules/idp.mod, start.d/idp.ini
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 enabling it as above you can edit the resulting properties file to configure it.
Configure Jetty to listen only on HTTP
File(s): modules/idp.mod, start.d/idp.ini
If your IdP is behind Apache, you probably only need it to listen for HTTP traffic locally. 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 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 are set apropriately in idp.ini, or remove them from there and add them to http.ini.
| Code Block |
|---|
jetty.http.host=127.0.0.1 |
...
jetty.http.port=8080 |
Since 8080 is the default http port for Jetty, It's also okay to leave this unset.