Installation

Before You Begin

Refer to the SystemRequirements page for details on supported software platforms.

See the SecurityAndNetworking page for introductory help in understanding the use of network ports, keys, and certificates.

A nice cross-platform GUI for manipulating Java keystores, PKCS#12 files, viewing certificates, etc., is Keystore Explorer. Most deployers, at least on Linux, tend to rely on OpenSSL’s command line for many such tasks.

Before you begin you should collect the following items and information:

• a TLS key/certificate that you'll use to secure your browser-facing HTTP(S) connection on port 443 (this is just a plain old low cost or even free commercial TLS certificate)

Assuming you plan to use the IdP for SAML support (as opposed to CAS support for example), you will need:

• the entityID URL you want to use to name your IdP (the installer will suggest one from your hostname, but this very likely is not be a good choice)

• the second- or third-level DNS subdomain to append to any "scoped" attributes, often the same as your organization's email domain

• the source(s) of SAML Metadata for the service providers your IdP needs to support (this could come from a "federation" of organizations you've joined, directly from the SP owners, or created and maintained by hand)

The installation process will suggest or generate the following information for you:

• the IdP's entityID (which you can override as noted above)

• separate self-signed key/certificate pairs for:

  • message signing

  • encryption of data by other systems for decryption by the IdP

• a secret key and key version file for securing cookies and other data produced by the IdP for its own use (this is a special Java keystore of type "JCEKS")

• some initial sample metadata describing the IdP for use by partner SPs, once it's reviewed and supplemented

• a default set of IdP configuration files based on this information

Windows-Specific Information

Per the warning above, the Windows installation and upgrade process for the IdP and Jetty are now largely the same in most respects as with any other supported platform. This section details a few Windows-soecific considerations for the IdP, while the JettyBasePlugincontains a lot of more specific information about Windows.

The only other major differences of note:

• The IdP distribution with a .zip extension should usually be used on Windows instead of the tarball, as the contents have the expected line endings.

• Be aware that contrary to usual practice on Windows, paths should always be specified using forward slashes ('/'). "DOS Devices" may however be specified, e.g.:

  -Didp.home=e:/opt/IdP

• To ensure that arbitrary accounts on a server do not have access (read or write) to the IdP configuration, see SetACLCommandfor details on the additional batch file provided when installing the IdP on Windows. This is not a prescriptive approach, but provides an example to look at in establishing limited rights for critical folders after installation.

IdP Installation

Per the SystemRequirements, the IdP is a standard Java web application (as of V5.1, based on the Jakarta Servlet 6.1 specification) and should run for the most part in any compatible servlet container, but official support is provided only for Jetty and Tomcat. Jetty is the strongly recommended option and is the primary environment we test and use for development of the software. Note that the Jakarta Servlet API is supported only by “later” containers as it is incompatible with the older long-time Java Servlet specifications.

The installation process is a command line process, not a graphical one.

1. Download the latest Identity Provider software package (the zip file has Windows line endings, the tarball Unix line endings).

2. Unpack the archive you downloaded to a convenient location. It will not be needed after installation.

3. Change into the newly created distribution directory, shibboleth-identityprovider-VERSION.

4. Run either bin/install.sh (on non-Windows systems) or bin\install.bat (on Windows systems).

   • The installation directory you provide will be referred to as idp.home throughout this documentation.

   • The installation directory cannot be the source/distribution directory.

   • Even on Windows, you MUST use forward slashes if specifying a non-default location.

Once the IdP installation or upgrade completes, you will need to install a servlet container (if not done previously), and finally deploy the IdP’s “war” file, located under war/idp.war in the installation location. In some cases, you may need or want to install additional IdP plugins first, as this tends to rebuild the war file. Deployment of the war file is discussed further in the section on container installation but tends to be container-specific.

Command Line Options

The install.sh / install.bat scripts support a number of command line options, noted below.

Servlet Container Installation

The recommended/suggested means of handling this is the JettyBasePlugin, an IdP plugin that is somewhat atypical compared to most IdP plugins, as it does not modify/extend the IdP’s features, but installs scripts and configuration files to support installing and maintaining Jetty and using it with the IdP software on all supported platforms. The packaging of it as a plugin is simply an installation and delivery convenience for the project, as well as a help in “scoping” use of the Jetty container to the IdP, which is always strongly advisable.

Its documentation is used in conjunction with this material to understand how to fully stand up the IdP. Its default configuration includes the deployment of the IdP’s war file into Jetty for you. Its documentation also describes the versions of Jetty it supports for particular minor versions of the IdP software. While its documentation may appear a bit daunting, it is in fact a fairly turnkey solution for getting up and running.

If you choose to install and manage a container on your own, then these historical topics may be of interest, as they include contributed material for various supported (and sometimes unsupported) containers, including deployment of the IdP. Always refer to the SystemRequirements page for the last word on what is officially required or supported.

• Jetty 12.1

• Jetty 12.0

• Tomcat 10.1

A Quick Test

You can test that the IdP is properly installed and is at least running successfully in a container with the Status command line utility (bin/status.sh or bin\status.bat).

If everything is working correctly, you should see output summarizing the environment and information about the IdP's state. This doesn't mean that you will be able to log into anything yet as you have not yet configured the IdP to use your organization's infrastructure, added metadata, etc.

Typical Next Steps

1. Review the top of the Configuration page to get some basic familiarity with the installation tree and how to use it.

2. Configure authentication.

3. Configure attribute resolution.

4. Try the Hello World feature for initial testing of authentication and attribute resolution.

5. Load SAML metadata for the service provider(s) with which you will interact and establish an appropriate attribute release policy.

6. Customize your login UI, error handling, etc.

Installing Plugins

Various extensions are also provided as plugins. IdP plugins are installed and interrogated using the plugin command line (bin/plugin.sh or bin\plugin.bat). See PluginInstallation for more details. (If you choose to use the JettyBasePlugin to handle Jetty installation and setup, you’ve already used it.)

Rebuilding the WAR file

Installing plugins automatically performs this step, but should you need to rebuild the war file yourself, you can run the build command line utility (bin/build.sh or bin\build.bat) from the installation directory(idp.home) at any time (though not with the IdP/container running).