WindowsInstallation

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.

Downloading and Installation

Download the appropriate MSI package for your system from https://shibboleth.net/downloads/identity-provider/latest4/.

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.

Open

• 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:

Open

• Note that the User Principal Name is domain qualified.

Jetty Configuration

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 are the properties 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.

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

If you chose to install Jetty, then an incoming  firewall exception will be added for the system service which runs jetty.   

Running Jetty as a Captive Account ^4.3

Up until V4.3 the system Service running Jetty was always run under the LocalSystem Account. Starting in V4.3 it is possible to run the service as a specified account (which need not have any privileges beyond “Log on as a a service”.

To use this you have to have created the account prior and given it the appropriate privilege prior to running and the installation. You might want to use a Service Account.

Then, during installation (or upgrade), click on the “Run as User” tick box and supply the credentials:

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:

1. run shibd_idpw

2. Go to the "java tab"

3. Unclick "Use Default"

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

If you tick the "Install Jetty" check-box then a minimal Jetty is installed and a service called shibd_idp is created to run the jetty installation.  By default the service will be started immediately but you can override this by running the the installer with the property ALWAYS_START_SERVICE set to “NO” (From V4.3).

C:\>msiexec /i IDP....msi ALWAYS_START_SERVICE=NO

Sometime the service not starting can cause the entire installation to be rolled back and this command is a useful guide to diagnosing these situations. In particular if you are running the service as a captive account you may need to check the password or, if you installation is advanced or non standard, to inspect or add to the ACLs on the file system.

Another common reason for the service not starting is that it could not locate the correct JVM.DLL  This can often be diagnosed by turning up the logging to debug in the shibd_idpw 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.

You can tell whether the service has started from an elevated command line

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.

C:\>msiexec /i IDP...msi NO_FIREWALL_EXCEPTION=true

Again, it needs to be reiterated that if you need control at this level you are approaching the level at which you would be recommended to install and manage you on separate jetty instance.

Post Installation tasks

If you have chosen to configure for active directory then much, but not all, of the configuration will have been done for you.  You do need to 

1. Complete LDAP configuration by providing the AD server's certificate information to the IdP in the ldap.properties file.

2. Complete Metadata configuration by providing the metadata for the SPs you will interoperate with in the metadata-providers.xml file.

See Configuration for more details

V3 to V4 Upgrades

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.

To upgrade, download the appropriate MSI package for your system from https://shibboleth.net/downloads/identity-provider/latest/ and run it. When the installer encounters an upgrade the only dialog is to ask whether Jetty is to be installed and to query the account details.

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.

Note that although the User Domain and Username are be remembered, the password is never stored and so always needs to be supplied on upgrade (if you are not using a Service Account).

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