Using Jetty 9

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 release. The latest stable version should be used.

Required Configuration

Recommended Configuration

Logging

TBD

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">
             <Item>SSLv3</Item>
          </Array>
        </Set>
        <Set name="IncludeCipherSuites">
          <Array type="String">
              <Item>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</Item>
              <Item>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</Item>
              <Item>TLS_RSA_WITH_AES_128_GCM_SHA256</Item>
              <Item>TLS_RSA_WITH_AES_256_GCM_SHA256</Item>
              <Item>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</Item>
              <Item>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</Item>
              <Item>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</Item>
              <Item>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Item>
              <Item>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</Item>
              <Item>TLS_RSA_WITH_AES_128_CBC_SHA256</Item>
              <Item>TLS_RSA_WITH_AES_256_CBC_SHA384</Item>
              <Item>TLS_RSA_WITH_AES_128_CBC_SHA</Item>
              <Item>TLS_RSA_WITH_AES_256_CBC_SHA</Item>
          </Array>
        </Set>
      </New>
    
      <!-- =========================================================== -->
      <!-- 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>
        </Call>
      </New>
    
      <!-- =========================================================== -->
      <!-- 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">
        <Arg>
          <New class="org.eclipse.jetty.server.ServerConnector">
            <Arg name="server"><Ref refid="Server" /></Arg>
              <Arg name="factories">
                <Array type="org.eclipse.jetty.server.ConnectionFactory">
                  <Item>
                    <New class="org.eclipse.jetty.server.SslConnectionFactory">
                      <Arg name="next">http/1.1</Arg>
                      <Arg name="sslContextFactory"><Ref refid="shibContextFactory"/></Arg>
                    </New>
                  </Item>
                  <Item>
                    <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                      <Arg name="config"><Ref refid="shibHttpConfig"/></Arg>
                    </New>
                  </Item>
                </Array>
              </Arg>
              <Set name="host"><Property name="jetty.host" /></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>
            </New>
        </Arg>
      </Call>
    </Configure> 
  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 your Jetty 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.

  1. 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>
    </Configure>
    

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