Jetty-Base Installation

The jetty-base installer MSI installs Jetty itself, a jetty-base configuration tree suitable for running an IdP on Windows, and other components needed to run the Jetty (with the IdP) as a system service. Thus, it includes:

  • The Apache Procrun executable which is used to run java programs as windows system service

  • The Jetty servlet container and web server

  • A jetty-base configuration that supports basic use of the IdP within Jetty

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 limited privileges and access.

Release History

  • Unreleased Jul, 2023 - Jetty12.0.8 (see below for important notes)

  • Nov 3, 2023 – Jetty 11.0.18

  • Oct 11, 2023 - Jetty 11.0.17

  • Aug 31, 2023 - Jetty 11.0.16

Prerequisites

You should 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.dll but it is safe to run the executable multiple times.

You should install a Java JDK (version 17 or greater - see https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/1177321655) and ensure that a system variable 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 is shibboleth-jetty-base-x64-<EmbeddedJettyVerson>.msi

Installation and Update

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

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 https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3254484996 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 Jetty 12

With the release of the jetty 12 version, the project is removing all support for managing the “backchannel”. Customers who need this should be managing their own jetty installations.

Prior to upgrading to Jetty12 for the first time, you should remove all use of the backchannel 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 you existing jetty installation will still support the backchannel). Once the metadata has propagated you can upgrade to Jetty12.

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

idp.backchannel.keyStorePassword idp.backchannel.keyStorePath idp.backchannel.keyStoreType

Further Configuration

(obviously) The IdP installation is fully configurable, 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.

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

msiexec /i msifile.msi [/qn] PROPERTY1=VALUE1 ....

The properties are:

MSI Property

Default

Description

MSI Property

Default

Description

ALWAYS_START_SERVICE

TRUE

If set to FALSE the installer does not try to start the service (failing to start the service can cause the install to unwind in which situation debugging the install can be aggravating and long winded)

NO_FIREWALL

 

By default the installer sets up a firewall exception for the system service. This property supresses it.

INSTALL_JETTYD_USER

 

Controls whether to set the system service to run as a specified user

JETTYD_USER

 

The specified user

JETTYD_DOMAIN

%USERDOMAIN%

The specified user’s domain

JETTYD_PASSWORD

 

The specified user’s password

Version Support

New Versions of the jetty-base installer are 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.