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 (or vc_redist.x86.exe for a 32 bit install).
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.
Failure to do this will result in an impenetrable and difficult to diagnose error - see
Install the appropriate Oracle Java runtime and set the JAVA_HOME environmental variable to point to the installation (My Computer->RightClick->Properties->Advanced System Settings->Environmental Variables->System Variables->New)
Install the MSI file and provide the necessary information prompted.
The installation location is where the IdP will be installed (the idp.home directory). When performing an upgrade, you should specify the location used before.
If you are not using the bundled Jetty container you will need to configure it to set idp.home to the installation directory (-Didp.home=C:/Program Files (x86)/Shibboleth/IdP) (but make sure that you avoid backlashes in the path you supply, as this will not function properly and is not supported).
The DNS name of the IdP should be something well-chosen and stable, and not the physical name of a server that might change.
The scope value should be a DNS subdomain, typically your organizational email domain, that will be used to compute the value of "scoped" attributes to make them unique.
Check the "Install Jetty" box if you want the installer to install and configure a Java container for you (but you should only do this if you can accept a very vanilla Jetty configuration). This will configure a system service called "shibd_idp" which can be controlled via the usual mechanisms or via the program C:\Program Files(x86)\Shibboleth\procrun\shibd_idpw.exe
If you check the "Configure for Active Directory" box, then you will see a second configuration page to provide connection details for Active Directory:
Note that the User Principal Name is domain qualified.
If you have chosen to install Jetty, then after installation, and before you configure the IdP, you may need to configure Jetty. Specifically you will want to configure the browser facing certificate and keypair for the HTTPS connector on port 443.
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 upgrades.
If you need to edit any file except idp.ini, then you are an advanced user and should deploy your own container. You can still use the Windows installer, but should uncheck the Jetty installation box.
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.
It has been observed (in ) that sometime the "Maximum memory pool" is not preserved. We have not been able to track this down yet, so always check after an upgrade that the settings have been preserved.
If you chose to install Jetty, then an incoming firewall exception will be added for the system service which runs jetty.
64 or 32 bit Installer?
You should install the version for the OS you are running. On a 64 bit machine you should install a 64 bit java and a use the 64 bit installer.
The 64 bit installer will not run on a 32 bit machine
The 32 bit installer will not run on a 64 bit machine.
If you configured jetty and installed the 64 bit installation on a machine which has a 32 bit Java installed then the service will not start. The best fix is to install a 64 bit Java, but you can force the IdP to run with a 32 bit Java by changing the procrun executable
C:\>sc config shibd_idp binPath= "\"C:\Program Files (x86)\Shibboleth\ProcRun\shibd_idp.exe\" service shibd_idp"
Java Installed from a .tar.gz file (tarball)
Some Java server installations are in the of a .tarball. For obvious reasons these installations from a tarball does not populate any registry settings which means that the Jetty installation cannot locate the correct jvm to run. This means that the shibd_idp does not start.
To fix this:
Go to the "java tab"
Unclick "Use Default"
Under "Java Virtual Machine" browse to %JAVA_HOME%\jre\bin\server\jvm.dll (for instance: C:\Program Files\java\jdk1.8.0_25\jre\bin\server\jvm.dll)
Troubleshooting the Jetty installation
This section is just about getting the Jetty installation running. For other troubleshooting see the Trouble Shooting guide
If you tick the "Install Jetty" check-box then a minimal Jetty is installed a service called shibd_idp is created to run the jetty installation. This service will automatically start, but if it does it is usually due to the specification of the Java run time.
You can tell whether the service has started from an elevated command line
C:\Users\Administrator>sc interrogate shibd_idp
[SC] ControlService FAILED 1062:
The service has not been started.
The easiest way to debug such a situation is by a combination of the parameters setting tool (procrun\shibd_idpw.exe), the procrun logs (procrun\log) and running the service from the command line (procrun\shibd_idp.exe or procrun\amd64\shibd_idp.exe on an x64 machine).
When you run shibd_idp.exe in a successfully configured system you will see something like this in the common-daemons.2015-01-29 log
[2015-01-29 14:09:07] [info] [ 2124] Commons Daemon procrun (184.108.40.206 64-bit) started
[2015-01-29 14:09:07] [info] [ 2124] Debugging 'shibd_idp' service...
[2015-01-29 14:09:07] [info] [ 2124] Starting service...
[2015-01-29 14:09:08] [info] [ 2124] Service started in 1092 ms.
In an unsuccessfully configured system it may look like this:
2015-01-29 14:07:30] [info] [ 1896] Commons Daemon procrun (220.127.116.11 32-bit) started
[2015-01-29 14:07:30] [info] [ 1896] Debugging 'shibd_idp' service...
[2015-01-29 14:07:30] [info] [ 1896] Starting service...
[2015-01-29 14:07:30] [error] [ 1896] Failed creating java
[2015-01-29 14:07:30] [error] [ 1896] ServiceStart returned 1
[2015-01-29 14:07:30] [info] [ 1896] Debug service finished with exit code 1
[2015-01-29 14:07:30] [error] [ 1896] Commons Daemon procrun failed with exit value: 3 (Failed to run service as console application)
This is usually due to one of two causes.
On an x64 machine, running against a 32 bit Java installation. This can be show since the 32 bit system service (procrun\shibd_idp.exe) will start but the 64 bit one (procrun\amd64\shibd_idp.exe) will not. This can be fixed by changing the image associated with the service as described above.
The service could not locate the correct JVM.DLL This can often be diagnosed by turning up the logging to debug in the parameter setting tool and closely inspecting the log. The procrun software goes to considerable lengths to find a workable JVM and we have not been able to make this fail in the lab, but you can force the JVM.DLL to be used in the Java tab of the parameters tool.
Supressing Firewall Exceptions
If you chose to install Jetty, then an incoming firewall exception will be added for the system service which runs jetty. This can be suppressed by running the the installer with the property NO_FIREWALL_EXCEPTION set to any value.
You are strongly recommended to upgrade your system to the latest V3 release and fix any deprecation warnings before upgrading to V4. This is not policed by the installer since it is not a requirement, but you will save yourself a world of pain by adding this intermediate step.
The V4 MSI installer will handle a V3 to V4 upgrade identically to a V4 to V4 upgrade.
V4 to V4 upgrades
The MSI installer is used to upgrade installations to later versions of the IdP.
The check box is set to the value that was selected on the previous install. As noted in the Upgrading topic, no existing configuration is overwritten by an upgrade and so no new configuration information is asked for. New configuration files may be populated, but existing files are never touched.
Service releases and "Same Version upgrades"
The Shibboleth IdP versioning follows the Shibboleth Java Versioning Policy. IdP versions consist of three numbers separated by a dot (for instance IdP V3.0.1 is Major Version 3, Minor Version 0, Patch Version 1).
The Windows Installer bundles other products (notable Jetty and Procrun) which have different lifecycles to the IdP and it may become necessary to ship an installer for the same IdP version but with revisions to the included products. In order to handle this a fourth digit is appended to the Installer version and this is changed if the bundled products have changed but the IdP hasn't.
For example, IdP version 3.1.4 might be shipped the Windows installer version 18.104.22.168. If Jetty then issued a security advisory which requires an upgrade to Jetty, then a new installer will be built for IdP Version 3.1.4 but with the latest Jetty, and given the Windows version 22.214.171.124. The IdP revision will be exactly the same, but the new and secure Jetty is included.
This new installer can be run on top of the 126.96.36.199 installation. As noted above no change will be made to the IdP configuration. Windows refers to this as a "same version upgrade". We usually refer to this as a "service release". We ship Service Releases in preference to shipping patches.
You can always find out the precise version installed by looking at the "Programs and Features" (or equivalent) menu in the control panel
The Windows installer does not allow you to go backwards with respect to the IdP installation (for instance V3.1.0 to V3.0.1), but it allows same version upgrades between any installation with the same Major, Minor and Patch version (for instance V188.8.131.52 to V184.108.40.206)