All maintenance for the Shibboleth Identity Provider V2 release branch ceased on July 31, 2016. All deployments should have upgraded to V3 or evaluate alternatives.
This is an installation guide. For an introduction to the identity provider or Shibboleth, please refer to Understanding Shibboleth.
Before you begin you should collect the following things:
The installation process will generate the following information for you:
Some older versions of Red Hat Enterprise Linux and CentOS ship with the GNU Java compiler and VM (
There have been reports of problems running the Shibboleth IdP on Debian 7 ("Wheezy") with an openjdk-6 package, which could be resolved by switching to openjdk-7 (
We strongly recommend the use of Oracle's "standard" JVM on all platforms. The OpenJDK implementation that ships with many Linux distributions is used by many deployers, but the community has off and on reported various problems that have frequently been traced to the use of OpenJDK, including memory leaks, the Debian issue above, and others. You should expect that reports of unexplained problems may be met with a request to reproduce them on Oracle's JVM.
The V2 Shibboleth Identity Provider is a standard Java web application based on the Servlet 2.4 specification and should run for the most part in any compatible servlet container. If you are unsure which to choose, most people use Apache Tomcat today, but Jetty is the strongly preferred option and is used by the primary team members in their production environments.
The officially supported containers are Jetty 7+ and Tomcat 6+. Containers for which we have specific installation help are shown in step 1 below, including some that we do not officially support. Material specific to any container is provided as a convenience, and is not a substitute for the container's own documentation.
After the installation script has completed the IdP home directory will have been created, here's a brief description of what you'll find in it:
The IdP metadata generated at install won't be dynamically updated if you change the Identity Provider's configuration or certificates. It is your responsibility to maintain this.
You can test that the IdP is properly installed and running by accessing the URL:
https://HOSTNAME/idp/profile/Status. If everything is working correctly you should receive an "ok" page. 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.
There is a second status page that provides additional information about the IdP.
After installation you will normally need to perform two steps in order to have a basic setup:
After you have finished that the next step is usually to collect and release attributes.
Version 2.3 and later
During first installation a self signed certificate with a lifetime of 20 years is generated. This lifetime can be adjusted by setting the environmental variable
IdPCertLifetime to the number of years desired.
During all installations, if a file called
web.xml in the
conf subdirectory of the IdP installation directory exists it is used in preference to the default file. This allows a customized
web.xml to be carried from release to release.
If you need to regenerate credentials without reinstalling the IdP, see IdPCertRenew.
Version 2.4 and later
Starting with version 2.4.0 of the IdP, there is an easier way to add content to the default Velocity templates that generate the POST response web page that is returned to the user's browser, and then auto-submitted to the appropriate SP endpoint. One has always been able to override those Velocity templates altogether, and create your own templates, if you know what you are doing. But this new feature for the IdP makes it much easier to make particular kinds of additions to those pages without needing to completely override the default pages.
Details on how to take advantage of this feature, and an example of adding Head and Body content, are found at AddPostPageHeadBodyContent.