WindowsInstallation

Downloading and Installation

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

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:

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

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"
  

Non JRE Installations

The component that the installation uses to run jetty only understand JRE layouts and may not be able to locate you copy of Java.  This will prevent Jetty (and hence the IdP) from starting)

To fix this:

1. run shibd_idpw
2. Go to the "java tab"
3. Unclick "Use Default"
4. Under "Java Virtual Machine" browse to the JVM

Troubleshooting the Jetty installation

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 (1.0.15.0 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 (1.0.15.0 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.

1. 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.
2. 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 ^3.3

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 shibboleth-identity-provider-3.xxx.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 V3 upgrades

The Windows 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 a V3 to V3 upgrade the only dialog is to ask whether Jetty is to be installed.

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