Page Comparison

...

Note

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

minLevel	2

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

We strongly recommend placing all IdP-specific Jetty configuration under JETTY_BASE to facilitate Jetty upgrades. Do not place that directory inside the IdP installation directory; they can be siblings as desired.

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 repositor, 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.

...

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.

start.ini

Code Block

language	text	title	start.ini

# 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.

...

One challenge remains that if you want to use standard ports, you would need to pick one of these options to avoid running as root:

...

Use the setuid extension to support listening on the privileged ports as a non-root user.
Use a port forwarding approach (load balancer, iptables rules, etc).
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

...

idp.ini

true

collapse

Code Block

# --------------------------------------- 
# 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

...

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.

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 /idp in the following configuration block.

idp.xml

Code Block

xml

language		title	idp.xml

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

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.

Configure logging policy for Jetty internals logging and request/access logging. Sample logback configuration files are provided for convenience and are in the resources directory.

...

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 (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.

...

web.xml addition

Code Block

collapselanguage	truexml

  <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>
    <load-on-startup>0</load-on-startup>
  </servlet>

...

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.

...

etc/tweak-ssl.xml

Code Block

collapselanguage	truexml

<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
          "http://www.eclipse.org/jetty/configure_9_4.dtd">
<Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="IncludeProtocols">
      <Array type="String">
         <Item>TLSv1.3</Item>
         <Item>TLSv1.2</Item>
      </Array>
    </Set>
    <Set name="ExcludeProtocols">
      <Array type="String">
         <Item>TLSv1.1</Item>
         <Item>TLSv1</Item>
         <Item>SSL</Item>
         <Item>SSLv2</Item>
         <Item>SSLv3</Item>
      </Array>
    </Set>
    <Set name="IncludeCipherSuites">
      <Array type="String">
          <Item>TLS_ECDHE.*</Item>
          <Item>TLS_AES.*</Item>
          <Item>TLS_RSA.*</Item>
      </Array>
    </Set>
    <Set name="ExcludeCipherSuites">
      <Array type="String">
        <Item>.*NULL.*</Item>
        <Item>.*RC4.*</Item>
        <Item>.*MD5.*</Item>
        <Item>.*DES.*</Item>
        <Item>.*DSS.*</Item>
        <Item>TLS_DHE.*</Item>
      </Array>
    </Set>
</Configure>

...

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 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.

...

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.

...

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.

...

Versions Compared

Old Version 15

New Version 16

Key

start.ini

Configure HTTP/HTTPS Connectors

idp.ini

Configure IdP Context Descriptor

idp.xml

Recommended Configuration

Jetty Logging

web.xml addition

etc/tweak-ssl.xml

Supporting SOAP Endpoints

Configure Jetty to listen only on HTTP