Page tree
Skip to end of metadata
Go to start of metadata

Out of date, needs revision.


The Identity Provider will be distributed in a few different ways:

  • tgz/zip archive
  • no-arch RPM
  • Windows MSI

Regardless of the distribution mechanism, the package will contain both the IdP and Jetty, a Java Web Server and Servlet container.  While the IdP may be deployed in any Servlet 2.5 compliant container, the bundled Jetty container will be the only option supported on the Shibboleth mailing lists.


Installation of the IdP will be driven by Gradle scripts.  As Gradle is just a set of libs on top of a programming language (Groovy), a lot of things that were very hard to do in Ant (e.g., branch logic) are now much easier.  Regardless of the distribution used, the installation script will be the same.

Once the distribution has been exploded, either manually by the user or automatically in the case of the RPM/MSI bundle, the installation script will do the following:

  • prompt the user for basic information: installation directory, hostname, browser-facing key and cert
  • set up the IdP installation directory (e.g., create the directory structure, copy over files, etc.) – see Installation Directory and Configuration Files for more information
  • generate the IdP's signing and encryption keypair and self-signed certificate
  • configure Jetty (both front- and back-channel ports)
  • write out basic IdP configuration files

After investigating the possibility of trying to use OS-native on-disk layouts for the installation (e.g., the Linux Filesystem Hierarchy Standard) this looks to be untenable. As such the layout of the IdP home directory will be the same on every platform. On the up side, this should also help with documentation.

After installation, deployers may need to perform additional OS-level configuration (e.g., opening up firewall ports, configuring the IdP to start when the system starts up).  The IdP will ship with example SysV/init.d scripts for Unix systems and Windows Service executables.

It has been requested, in the past, that the installation process be able to take in federation specific data and use that when writing out the IdP's initial configuration files.  This remains an open item to be investigated once the basic installation script is complete.  See below for some additional installer functionality that may satisfy this need.

Initial Configuration Files

During installation, the process will give the user the option to answer some additional questions in order to customize the initial configuration files that are written out.  These additional data include:

  • LDAP hostname, port, user filter, connection username/password (optional)
  • metadata URL and signature verification certificate

Provided this information, the IdP can configure authentication and attribute retrieval from the LDAP directory and consumption of metadata from a well-known URL.  This setup corresponds to the majority of current IdP deployments and so should get people up and running more quickly.  Note, however, this step is not meant to cover all possible configurations but instead to simply give a starting point.

In the event that a deployer chooses not to provide the above information during installation (e.g., because they aren't using LDAP), the installation script will still write out configuration files, they'll just be more generic and require more post-installation tweaking.


The upgrade process, like the installation process, will be driven by Gradle scripts.

The upgrade script will perform a few tasks:

  • update Jetty
  • update the IdP war
  • upgrade existing configuration files with new features when possible
  • write out the latest "pristine" configuration files as .dist files so that deployers can always compare their current configuration files with what they would get if they performed a brand new installation

As noted in the description of the Installation Directory and Configuration Files, some directories will be completely overwritten by the upgrade script.  This should make it clear that deployers should not be making any changes to items in these directories.  An outstanding question, however, is how to deal with extensions.  Likely this will be done by creating a specific directory to which extensions are "installed" and the upgrade script will copy such files to the appropriate place.

Upgrading from 2.x

Unlike the upgrade for IdP v1 to v2, the plan is to provide some support for upgrading an existing v2 installation.  This will not be an in-place upgrade, thus at the end of the process the deployer will have two IdP home directories (one for v2 and one for v3).  While most configuration files can be upgraded, the following items will not be handled by the upgrade script:

  • custom extensions - the v2 -> v3 migration logic will simply ignore them
  • login and error pages - these pages are specified as JSPs in v2 and Velocity templates in v3 and there is no way to programmatically transform from one to the other
  • No labels