Page tree
Skip to end of metadata
Go to start of metadata

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

FileRL?PurposeTasks
Core Configuration
attribute-map.xmlY(*)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.xmlYControls 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.xmlY(*)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.xmlYDefines 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.xmlYRoot 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.pemYPrivate 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.pemYPublic 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.pemYPrivate 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.pemYPublic 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.htmlYTemplate displayed when the optional Attribute Checker Handler is used to detect missing attributes during session creation
  • Customizing the response from that handler
bindingTemplate.htmlYTemplate 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.htmlYTemplate 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.htmlYTemplate displayed at the completion of a logout operation that did not include the IdP.
  • Customizing the response when logout isn't really logout
metadataError.htmlYTemplate 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.htmlYTemplate displayed when a logout operation is detectable as having failed to complete.
  • Customizing the response when logout isn't complete
postTemplate.htmlYTemplate 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.htmlYTemplate 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.htmlYTemplate 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
  • No labels