Jetty on Windows Installation

We provide a Windows installation package for the Jetty container software to simplify installation and upgrades. The nstaller MSI installs Jetty itself, ajetty-baseconfiguration tree suitable for running the IdP software on Windows, and other components needed to run Jetty as a system service. Thus, it includes:

• The Apache Procrun executable which is used to run Java programs as Windows system services

• The Jetty servlet container and web server

• Ajetty-baseconfiguration that supports basic use of the IdP within Jetty, largely derived from our examples

It does sufficient configuration of all these subsystems to allow the IdP to be started and run, either under the standard system account or as a specified user. Such a user would usually be given more limited privileges and access.

Release History

• Sep 10 2023 - Jetty 12.0.13 (see below for some important notes and caveats)

• Nov 3, 2023 – Jetty 11.0.18

• Oct 11, 2023 - Jetty 11.0.17

• Aug 31, 2023 - Jetty 11.0.16

Prerequisites

You must install and download the "Visual C++ redistributable packages for Visual Studio 2015, 2017 and 2019".  At the time of writing this is available from this link. You need the file vc_redist.x64.exe  You can establish whether this is needed by looking for the file c:\Windows\system32\ucrtbase.dllbut it is safe to run the executable multiple times.

You must install a Java JDK (Version 17 or greater - see Java Distributions) and ensure that a system environment variable named JAVA_HOME points at the installation.

Downloading

Download the appropriate MSI package for your system from Index of /downloads/identity-provider/jetty-windows

The name of the installer isshibboleth-jetty-base-x64-<EmbeddedJettyVerson>.msi

Installation and Update

The process for new installation or update is very similar only one configuration dialog is presented

Open

This dialog allows you to

• Specify whether to run as the built-in account or a specified account

• If ‘Run as as User’ is ticked you must specify

  • The Domain (defaults to the local domain),

  • Username,

  • and Password (may be null)

This dialog is presented on installs and updates. The Domain and Username are remembered across updates, but the password is not.

The supplied user can be any valid user, but it does have to have “Logon as Service” User Rights.

Jetty and Procrun are installed into \Program Files (x86)\Shibboleth and the jetty-base installed below your shibboleth install.

Appropriate ACLs are placed onto the IdP installation using SetACLCommand and explicit calls to icacls. This allow Administrators full access and no-one else access. Thus all management needs to be done from an elevated process. Additionally, if 'Run as as User' is specified then that user is given read access to the IdP installation and write access to the log folders:

• %IDP_HOME%\logs

• %IDP_HOME%\logs

• \Program Files (x86)\Shibboleth\log

Updating to or Using Jetty 12

With the release of the Jetty 12 container, the project is removing all support for managing the “backchannel”, which is a secondary virtual host listening on a separate port and supporting client TLS authentication. Deployers requiring support for SAML Artifact binding or Attribute Query profile usage should consider migrating that support to the standard port 443. The IdP will rely on message signature verification rather than TLS client authentication for securing those requests.

Prior to upgrading to Jetty 12 for the first time, you must complete this migration to port 443 and update and distribute your metadata appropriately. You should NOT remove the backchannel properties from jetty-base\start.d\idp.ini at this stage (since your existing Jetty installation will still expect the properties). Once the metadata has propagated and traffic has been tested and migrated, you can upgrade to Jetty 12.

After the installation, you should then update your jetty-base\start.d\idp.ini to remove these backchannel properties:

Further Configuration

Your separate IdP installation is of course fully configurable as normal, but the only configuration of Jetty which is available to you is in the file %IDP_HOME%\jetty-base\start.d\idp.ini, and you should not edit any other file in the jetty-base directory, let alone files in the Jetty installation directory, because you will lose these changes when you perform Jetty upgrades.

You must not add any modules to the configuration or do any configuration in this file which is not the editing of the 6 properties provided in the default version of this file.

If you need to edit any file except idp.ini, (or make changes to idp.ini beyond changing the 6 properties), then you are an advanced user and should deploy your own container. You can still use the Windows Installer for the IdP itself if you choose.

You may choose to make changes to the Java environment in which Jetty runs via the c:\Program Files (x86)\Shibboleth\Procrun\shib_idpw.exe program. Typical changes include changing the memory requirements or adding system variables (required by plugins). The only change which will survive an upgrade is the "Maximum memory pool". All other changes will not survive an upgrade. If you need to make substantial or long lived changes you should consider installing your own container.

Properties

The jetty-base installation can be driven from the command line by using msi properties

The properties are:

Version Support

New versions of the Jetty installer are normally tested with the current IdP version, but with no previous ones. While the IdP version should in general be independent of the Jetty installer version the only supported versions are the latest Jetty installer on the latest IdP release.