General guidance

Typically the IdP installation directory is /opt/shibboleth-idp on Linux, or C:\Program Files\Shibboleth\IdP or C:\Program Files (x86)\Shibboleth\IdP on Windows. The installation directory is referred to in configuration files as %{idp.home}, and we refer to it as such here. Configuration files are located in the conf subdirectory of the IdP installation directory, that is to say %{idp.home}/conf.

Take configuration a step at a time; work on a particular configuration task, and test and modify your configuration until you have achieved the desired result. Check the idp-process.log and the container logs.

You can get more information by turning the logging level to DEBUG while you're configuring the IdP. To get details for many of the important processes in the IdP, set the following 3 parameters in %{idp.home}/conf/logback.xml to DEBUG:

    <!-- Logging level shortcuts. -->
    <variable name="idp.loglevel.idp" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.ldap" value="WARN" />
    <variable name="idp.loglevel.messages" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.encryption" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.opensaml" value="INFO" />
    <variable name="idp.loglevel.props" value="INFO" />

Reference documentation for logging configuration is available on the Shib wiki.

Generally we suggest the following order for configuring the IdP:

  • user login, configuration usually in or jaas.config
  • federation metadata
  • register
  • test
  • attribute release in attribute-filter.xml and attribute-resolver.xml
  • customise login page, configuration in views/login.vm, messages/, views/login-error.vm, messages/ Refer to Login page Customisation
  • perform any tasks required for going into production