ConfigurationFileSummary

Owned by Scott Cantor
Last updated: Nov 29, 2021
4 min read

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

Â