Configuration

Configuration Overviews and References

Topics exist for each general configuration area to go into detail on how to do various things and to provide a definitive reference on configuration settings. Before digging into details, you should take a look at the layout summary below to get a general idea of where things live.

Review these topics first, just to get the lay of the land, and because debugging your changes will usually require some logging familiarity.

You will likely want to at least skim these general topics before really diving in. Some of it won't make sense but it's important to have some of the concepts in mind when you actually try to configure anything. You need a plan for how this is intended to be used with your applications before you get serious about setting it up. This is middleware and highly abstract compared to setting up a tradtional piece of software.

Application Integration
Attribute Access
Application Model (a bit more conceptual)

Most of the configuration is a combination of XML to specify things that are mostly about SAML and general software matters and, in the case of Apache, a large set of commands and options in its native configuration format. You should be comfortable with XML, have at least a general working knowledge of SSO systems, and have significant knowledge of the web server you're using independent of Shibboleth, or you will struggle and become frustrated. The SAML part will just add to your confusion if that's not the only new piece for you.

To configure a new SP from scratch, you will address these areas (most of this is covered without context in the Getting Started topic):

Advanced configuration topics:

Full Reference

A full reference to all the options and settings can be reached by starting at the <SPConfig> root topic, which is the element at the root of the shibboleth2.xml file, the core configuration file.

Installation Layout

The following summary will guide you in understanding the installed software layout and how to locate important files. The layout will be mostly familiar to those experienced with Linux/Unix software. The exact directories will vary based on how the installation is done and the system CPU architecture. On Windows there are both 32-bit and 64-bit files on a 64-bit OS.

Many of the directories are "built-in" to the software at build time to allow the use of bare filenames or relative paths in the configuration. It's also possible in unusual cases to override most of the individual paths with environment variables.

sbin[64]	"System"-level executable programs, e.g. the shibd daemon lives here
bin[64]	Contains some command line programs, and some general utilities (e.g. openssl and curl on Windows)
lib[64]	May contain libraries included with the software if not installed in a more general location.
lib[64]/shibboleth	Plugins and web server modules
etc/shibboleth	Contains most/all of the SP's configuration files, templates, and example scripts. Genrally "live" web server configuration is not here but examples may be. This is also typically where the SP's private key and certificate credentials are located, and is where certificates used to verify signed metadata are placed. During any installation (first time or upgrades), modified files are never replaced in this directory. New files required by the SP version being installed will be populated if and only if they do not exist. Generally each packaging mechanism we support is programmed to do the reasonable thing within its capabilities to keep systems working properly. Copies of the original versions of many of the files are copied here with a .dist extension for ease of comparison, but none of these files are live and can be deleted if desired.
doc/shibboleth	Contains documentation, licenses, and the like.
var/log/shibboleth	Contains the shibd.log and transaction.log files by default, though logs can be sent to arbitrary places.
var/cache/shibboleth	Contains files created by the software that should survive system restarts, such as backup copies of remote metadata or configuration files and HTTP caching information. Files may be deleted when the software is not in use without preventing future use unless a remote source of configuration is unavailable.
var/run/shibboleth	Contains temporary files created by the software that are expected to be transitory and not survive a system restart. Typically PID files, socket files, and the like.