V5 IdP Installer

The idea behind this page to capture some thoughts about the IdP installer over and above the point changes discussed in https://shibboleth.atlassian.net/browse/IDP-2105

With a following wind this should turn into the detailed documentation for V5

Architectural overview

I had some original thoughts to split the installer into smaller sub parts, but it turns out that on further code reading the current implementation is no too far from OK. The way it is exposed (via an ant task) sucks and as per https://shibboleth.atlassian.net/browse/IDP-1815 we can get much of where we want to just by replacing that.

The core of how the Installer (and here I also include build.sh) works is a class which contains (and captures where needed) the implementation. Thing like source directory, target directory detailed configuration (for new installs). Currently this class is populated

  • From System Properties

  • From an supplied property file

  • And from the command line (if neither of the above two provide the required value)

The first two bullets have proven popular with people bundling the IdP.

The proposal is to keep this but to add to it with proper command line qualifiers

  • Probably one for each property we have

  • And we will add properties for things we some add (like HttpClient bean names or aes key sizes), but not for other CLI things (like spring bean files)

  • We will do away with the special logback file for the installer and replace it with the standard command line thing

  • I think we can get rid of the input property - you can only install from the distribution and it suffices to make that the input

Note that when I say “property driven” below this means via this class which encapsulates the above 4 bullets (so if configured, take from the command line/property file/system properties otherwise ask)

Current implementation

As the time of writing (the first pass of changes for https://shibboleth.atlassian.net/browse/IDP-2002 completed the code does this.

Initial Populate

  • Update only: Tidy

    • delete bin/lib

    • delete dist (save for the plugin stuff)

    • unprotected system

  • Copy webapp to dist\webapp (not overwriting)

  • Copy bin/lib to bin/lib (overwriting)

  • copy system to system (not overwriting)


  • Version handling

    • Write the version to a the version file in dist

    • check idp.properties for forbidden properties

    • Check plugin conformance

  • New Install Only:

    • Enable idp.Core

    • Create key material (property driven)

    • Run property changing over idp.properties, ldap.properties (property driven)

    • create secret.properties (prooperty driven)

  • Update only

    • check edit-webapp\WEB-INF\web.xml for badness

  • enable modules

    • Update: The ones already defined

    • (TODO) V4-V5 update: plus any new ones ( )

    • New Install Only: from a fixed list (if not property driven)

  • Clean up detritus

  • New Install Only: Create metadata (driven from idp.properties)

Build war

(this is part of the install but also needs to be its own command line)

  • delete webapp (why?)

  • create webapp.tmp

    • populate from dist\webapp

    • overlap from dist\plugin-webapp

    • overlap from edit-webapp

  • create war\idp.war from webapp.tmp

  • delete webapp.tmp


This is actually not much different

  • Initial Populate is handled by the Windows MSI installer

  • Configure and Build war are run as java programs inside the installer

  • … Plus a whole lot of stuff to do with Jetty which will be exbedded ( or something else)

Properties & Qualifiers used to drive the Install

Under construction

This section os changing frequently as I update my ideas. Check in here frequently or watch the page.


V5 Proposed qualifier





V5 Proposed qualifier








The first thing looked it. If present it is used to get other properties

Not as a property




No longer prompted for. This is injected by the install scripts




Installation Directory:






If the qualifier is present (or the property set to any value) then if a required value is not available via properties then the install fails (rather than prompting for a value)




SAML EntityID:

Written into idp.properties on initial install



Some nasty hackery with the network

Host Name:

Drives the default entityId
Drives the default scope
Drives the subjectAltName
Drives the metadata
Drives key generation



The host name with the first bit removed

Attribute Scope:






A property file whose contents are merged into the default idp.properties on an initial install only.
This is either the absolute path or a path relative to the source dir



no merge


If present this file is merged into ldap.properties

This is either the absolute path or a path relative to the source dir





Used to set idp.authn.LDAP.bindDNCredential in secrets.properties




Backchannel PKCS12 Password:

Password for credentials/idp-backchannel.p12
Are we going to keep om generating this?




Cookie Encryption Key Password:

Password for credentials/sealer.p12





Alias in credentials/sealer.p12





New In V5
AES key size for credentials/sealer.p12





key size for credentials\idp-signing.*, credentials\idp-encryption.* and credentials/idp-backchannel.p12





whether to lock down the installation
bin/*.sh 755
system/* 444
dist/* 444
dist/plugin* 640

New install only:
credentials/* $idp.conf.credentials.filemode
credentials/* group $idp.conf.credentials.group (if present)





Mode to set credentials/* on a new install if $idp.conf.setmode





If non-null and $idp.conf.setmode, the group to set on credentials/*





Debug only if set to anything then any intermdeiate files (like the merge files) are not deleted.



idp.EditWebApp (V5) idp.CommandLine (V5) idp.authn.Password idp.admin.Hello


Comma-separated list of modules to enable on install. If this starts with '+' then the valuse are appended to the list.

ant.home (v4)


From where the installer is being run


Not available in V5

idp.conf.preoverlay (V4 only)




No longer Used, proposed alternative is to write a plugin and get that installed

idp.initial.edit-webapp (V4 only)




No longer Used, proposed alternative is to write a plugin and get that installed