ConfigurationFileSummary

To help orient you, a summary of the general function of each file follows along with a tip for when or why you might care about it. The order is alphabetic, not based on the frequency of use.

The "RL?" column notes which files can be reloadable, but not necessarily which ones are since that may depends on various properties in shibboleth2.xml

File	RL?	Purpose	Tasks

File	RL?	Purpose	Tasks
Core Configuration
attribute-map.xml	Y(*)	Maps incoming SAML Attributes and/or NameID Formats into local variable/header names within the SP. The asterisk refers to the fact that this file should generally only be marked reloadable if you take care not to rely on HTTP request headers to consume the data.	Determining the data the SP consumes from IdPs and what to call it
attribute-policy.xml	Y	Controls rules for accepting incoming data from IdPs. Comes with a useful set of default rules for certain kinds of attributes and usually isn't needed very often beyond that.	Adding additional "scoped" attributes Rejecting certain attributes from certain IdPs (e.g. self-asserted names or email addresses) Adding custom attributes only valid for a specific IdP
protocols.xml	Y(*)	Defines underlying default paths and low level details that allow the system to auto-configure itself via the `<SSO>`, `<Logout>`, etc. elements. It isn't usually modified by deployers. It could be reloadable but has no effect until the core configuration is reloaded.	Generally none, but could be used to alter the default paths where SAML messages are processed
security-policy.xml	Y	Defines low-level rules for securing SAML message processing, and also supports explicitly turning off compromised cryptographic algorithms or overriding system defaults in that area. Rarely modified by deployers.	Adjusting algorithm rules if the system defaults aren't suitable Creating advanced rules for processing messages specific to particular IdPs (very unusual)
shibboleth2.xml	Y	Root configuration file of the SP, this is the main starting point for all changes and tasks excluding altering content rules on Apache	Just about everything that's not somewhere else, but particularly initial setup, adding metadata, adjusting session timeout, and content rules for IIS deployments
Logging Configuration
console.logger		Configures logging of the command line tools and the shibd command line when the configuration is "tested"
native.logger		Configures logging from the web server modules	Altering the default level Routing messages to a remote syslog collector
shibd.logger		Configures logging of the shibd process and the transaction/audit log (the actual transaction log format string is set in shibboleth2.xml)	Altering various logging levels Routing messages to someplace other than a local file
Credentials
sp-signing-key.pem	Y	Private key generated by installer used for signing of messages or client TLS authentication directly to IdPs	Overwriting your own signing key from a different install of the software
sp-signing-cert.pem	Y	Public key certificate generated by installer used for signing of messages or client TLS authentication directly to IdPs	Overwriting your own signing key from a different install of the software
sp-encrypt-key.pem	Y	Private key generated by installer used for decryption of incoming encrypted data from IdPs	Overwriting your own decryption key from a different install of the software
sp-encrypt-cert.pem	Y	Public key certificate generated by installer used for decryption of incoming encrypted data from IdPs	Overwriting your own decryption key from a different install of the software
Useful Scripts
keygen.sh / keygen.bat		Wrapper around openssl command line to generate new keypairs, with some "defaults" baked in that match the behavior of the SP installation process	Generating new key pairs with more specialized requirements than the installation process assumes
seckeygen.sh / seckeygen.bat		Simple script that maintains secret keys in a flat file format for use with the SP's stateless clustering feature	Schedule as a daily task to repeatedly change the secret key while holding on to older versions
metagen.sh		Example bash script that can generate SP metadata with various bits and options turned on and off, mostly provided as a sample and will eventually be moved over to the IdP where it's more useful
User Interface Templates
attrChecker.html	Y	Template displayed when the optional Attribute Checker Handler is used to detect missing attributes during session creation	Customizing the response from that handler
bindingTemplate.html	Y	Template displayed when POST-based SAML messages are sent by the SP. Redirect is more common, but some IdPs require POST.	Customizing the "placeholder" page that displays during these transitions Changing the Javascript used by the page if e.g. you want to apply CSP headers across your application
globalLogout.html	Y	Template displayed at the completion of a SAML logout operation that involved communication back to the IdP.	Normally nothing because the typical convention by IdPs is to display the final result from the SP in a hidden iframe
localLogout.html	Y	Template displayed at the completion of a logout operation that did not include the IdP.	Customizing the response when logout isn't really logout
metadataError.html	Y	Template displayed when a user-visible error occurs that is assumed to be metadata-related, usually lack thereof	Customizing the appearance of "IdP not found" conditions
partialLogout.html	Y	Template displayed when a logout operation is detectable as having failed to complete.	Customizing the response when logout isn't complete
postTemplate.html	Y	Template that carries "recovered" POST submissions after a SSO round-trip	Customizing the "placeholder" page that replays a form submission after SSO Changing the Javascript used by the page if e.g. you want to apply CSP headers across your application
sessionError.html	Y	Template displayed when general error conditions arise during operation that are not apparently metadata-related	Customizing the appearance of general errors, including non-successful responses from IdPs
sslError.html	Y	Template displayed when "redirectToSSL" setting is used and a POST is detected, not commonly an issue
External Configuration Examples
apache.config apache2.config apache22.config apache24.config		Example configuration snippets for various Apache versions, should not be included directly as they get overwritten during upgrades	Examples to copy to your Apache configuration
shibd-amazon shibd-debian shibd-redhat shibd-suse shibd-systemd shibd-osx.plist		Mix of contributed and incorporated init scripts for shibd startup management	Examples for your own use if existing packaging is insufficient