The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.

ConfigurationFileSummary

The configuration file count is much larger in V3 compared to earlier versions, partly due to new features, partly because we have created smaller units of configuration dealing with specific tasks, and partly because we've tried to expose more options directly without requiring code changes or plugins. In practice, you should expect to interact with the same files as in earlier versions on a regular basis and you may never touch many of these files.

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 depends on the "checkInterval" properties in services.properties.

FileRL?Purpose Tasks
access-control.xmlYControls access to administrative functions like the status page, resolver testing tool, service reloading, etc
  • Changing IP address restrictions on access to "admin" URLs
attribute-filter.xmlYAttribute release policy controlling whether to return attributes to a requester
  • Controlling the SAML Attributes provided to SPs during SSO or via a Query
attribute-resolver.xmlYHow attribute data is produced from LDAP, database, or other data sources, and how it's encoded into SAML or other formats (i.e., the formal name(s) used)
  • Obtaining or producing the SAML Attributes supported by the IdP
  • Legacy support for producing some SAML NameID subject identifiers
admin.xml 3.3NDescribes supported administrative flows to the IdP
  • Adding custom new administrative or user management features
  • Configuring authentication and access control requirements for administrative features
audit.xmlNControls general audit log behavior
  • Add or change audit log entry formats
  • Exclude a profile from auditing
  • Add a custom audit field with Java or scripts
cas-protocol.xmlNConfigure CAS protocol features
credentials.xmlYConfigure private keys and certificates. This is unused after a V2 upgrade until the relying-party.xml file is (manually) converted from deprecated V2 format to V3 format.
  • Add additional signing or encryption keypairs
  • Enable a second encryption key during a key rollover
errors.xmlNError handling configuration, controls which "events" are mapped to SAML errors, and how to signal them
  • Map events to alternate view templates
  • Control whether events short-circuit SAML responses or not
  • Customize SAML and SOAP status codes
global.xmlNA place to put globally visible custom Spring bean definitions, empty by default
  • Override built-in behavior of low-level components such as storage or session management
  • Create utility bean definitions to help define other custom beans located elsewhere
  • Override built-in global algorithm blacklist
idp.propertiesNJava property file used to change common or important settings more easily, and as a pointer to additional property sources
  • Add additional property files
  • Set important global settings like the unique entityID of the IdP, the attribute qualifying scope/domain, pathnames and passwords for keys
  • Change lots of globally significant settings
ldap.propertiesNJava property file with LDAP authentication and attribute lookup settings
  • Configure general LDAP location, credentials, and search properties
  • Use separate directories for authentication and attribute lookup
  • Add additional LDAP sources
logback.xmlYLogback logging configuration
  • Change logging levels, locations, file retention behavior
  • Add custom log destinations (e.g., syslog)
metadata-providers.xmlYConfigure sources of SAML metadata (initially a copy of relying-party.xml after a V2 upgrade)
  • Add metadata sources
  • Control metadata verification and filtering
mvc-beans.xml 3.2NA place to put custom bean definitions for the Spring MVC layer, empty by default
  • Mostly just for extension authors if they need to make changes or additions like adding MVC controllers or adding new view technologies
relying-party.xmlYControls which profiles are enabled for which relying parties and the profile settings used with them
  • Turn profiles on and off
  • Customize profile features like signing and encryption, attribute push/pull
  • Set preferred authentication types based on RP or profile
  • Turn special intercept flows on and off (e.g. attribute consent, usage terms, permission checks)
  • Enable "open" operation without metadata
saml-nameid.propertiesNJava property file with settings controlling SAML NameID generation and consumption
  • Toggle between stateless and in-memory transient identifiers
  • Toggle between hash-generated and database-backed persistent/pairwise identifiers
  • Changed default NameID formats
  • Toggle legacy use of attribute resolver to generate NameIDs using AttributeEncoders
saml-nameid.xmlYControls generation of SAML NameIDs (a simpler replacement for the legacy capability to do this using AttributeEncoders)
  • Turn on or off transient and persistent identifier support
  • Configure custom NameIDs based on resolved attributes
services.propertiesNJava property file with pointers to the resource collections that configure important services and settings controlling configuration reload policy
  • Customize the reloadability of various service configurations
  • Control fail-fast behavior at startup
  • Override the resources that configure services without editing services.xml
services.xmlNControls the resources loaded to configure important services, and allows for advanced resource types such as subversion
  • Add or change resources loaded to configure metadata, relying party settings, attribute resolution and filtering, and other services
  • Add Spring configuration in support of advanced resources like Subversion files or HTTP resource requirements such as TLS certificate checking
session-manager.xmlNConfigures behavior associated with session management but not handled with properties
  • Adding session types and logout configuration for new extension features not built-in to the IdP software

admin/
general-admin.xml
3.3

NDescribes supported administrative flows to the IdP
  • Add new administrative flows
  • Customize flow settings such as authentication or access control rules
admin/
metrics.xml
3.3
NConfigures customizable instrumentation and reporting features
  • Enable or disable metrics
  • Configure metric reporting features
  • Enable customized timers or counters
authn/
authn-comparison.xml
NEstablish relationships between authentication methods in terms of protocol-specific identifiers such as SAML AuthnContext classes
  • Support non-exact matching between requested and supported authentication methods, such as indicating that a multi-factor method is "better than" a password
authn/
authn-events-flow.xml
NA webflow definition file for enumerating custom events to use as the result of custom authentication flows
  • Support a custom Event as the result of an authentication flow for error handling purposes
authn/
duo-authn-config.xml
3.3
NConfigures Duo Security login flow
  • Integrate the IdP with Duo Security as a second factor, usually driven with the MFA login flow
authn/
duo.properties
3.3
NJava property file that holds Duo integration settings
  • Connect the IdP to your Duo service as a registered Duo Security application
authn/
external-authn-config.xml
NConfigures External login flow (this is the comparable method to V2's External flow)
  • Change the location of the external authentication servlet
  • Map events for error handling purposes
authn/
general-authn.xml
NDescribes supported authentication flows to the IdP
  • Add new authentication flows
  • Customize flow settings such as timeouts, and mappings to protocol-specific authentication types/classes
authn/
ipaddress-authn-config.xml
NConfigures IPAddress login flow
  • Create rules associating network ranges to principal names to login as
authn/
jaas-authn-config.xml
NConfigures JAAS back-end for Password login flow (this is the comparable method to V2's UsernamePassword flow)
  • Change the location of the JAAS config file
  • Chain login module together across separate JAAS "application" entries
authn/
jaas.config
NConfigures JAAS login modules to use with JAAS login flow
  • Specify the JAAS login modules to use and their settings and associate them with "application" names
authn/
krb5-authn-config.xml
NConfigures Kerberos back-end for Password login flow (this is a username/password validation flow, not a ticket- or desktop-based flow)
  • Change some simple options like krb5.conf refresh and ticket caching
authn/
ldap-authn-config.xml
NConfigures LDAP back-end for Password login flow (this is a native LDAP password validation flow)
  • Use more advanced search or bind strategies not supported by properties
  • Configure support for communicating account state based on password or account policies
authn/
mfa-authn-config.xml
3.3
NConfigures multi-factor authentication login flow
  • Build scripted, dynamic workflows involving multiple login methods and other business logic
authn/
password-authn-config.xml
NConfigures overall Password login flow
  • Choose which back-end to validate the password with
  • Control form field names
  • Configure simple transforms of username entered
  • Map Events and exception messages from back-ends for error-handling purposes
authn/
remoteuser-authn-config.xml
NConfigures RemoteUser login flow (this is the comparable method to V2's RemoteUser flow)
  • Change the location of the protected location
  • Map events for error handling purposes
authn/
remoteuser-internal-authn-config.xml
NConfigures InternalRemoteUser login flow (this is similar to the V2 RemoteUser flow, but with no extra redirections)
  • Configure use of headers or attributes to get username
  • Configure simple transforms of username
  • Limit usernames to accept

auth/
spnego-authn-config.xml
3.2

NConfigures SPNEGO login flow
  • Kerberos service configuration
  • Control the interaction of SPNEGO with password login
authn/
x509-authn-config.xml
NConfigures the X509 login flow
  • Configure location of a template that prompts for a certificate
  • Map events for error handling purposes
authn/
x509-internal-authn-config.xml
NConfigures the X509Internal login flow (this is the same as the regular one, but with no extra redirections)
  • Configure advanced rules for validating the certificate instead of relying on the container
c14n/
attribute-sourced-subject-c14n-config.xml
NConfigures a mapping of the logged in username to an internal username based on resolving attributes from LDAP, a database, etc.
  • Remap usernames after login to different values derived from the attribute resolver
c14n/
simple-subject-c14n-config.xml
NConfigures simple transforms of logged in username after authentication
  • Remap usernames after login to different values based on simple transforms
c14n/
subject-c14n-events-flow.xml
NA webflow definition file for enumerating custom events to use as the result of custom canonicalization flows
  • Support a custom Event as the result of a canonicalization flow for error handling purposes
c14n/
subject-c14n.xml
NConfigures mechanisms for processing usernames after authentication, and for mapping SAML NameID values back into usernames
  • Change how usernames are transformed after login
  • Turn off legacy PrincipalConnector feature in Attribute Resolver
  • Support Attribute Queries or other advanced SAML features based on custom identifier types
c14n/
x500-subject-c14n-config.xml
NConfigures how to extract a username from end-user client certificates
  • Support X.509 certificate authentication and map part of subject DN or subjectAltNames into username
intercept/
consent-intercept-config.xml
NConfigures built-in attribute release and terms of use features
  • Control the terms of use message to present based on the RP
  • Control which attributes are subject to consent
  • Change the audit logging formats and categories used by these consent features
intercept/
context-check-intercept-config.xml
NConfigures built-in flow that blocks a profile request if it meets (or doesn't meet) pluggable criteria, for example preventing SSO if an attribute is not available
  • Configure the condition to apply to the request state before allowing it to continue, such as attribute(s) and value(s) to require for specific RPs
 intercept/
expiring-password-intercept-config.xml
3.3
NConfigures built-in flow that warns a user of an expiring password based on a resolved attribute
  • Configure the attribute to check for, how to parse it, and how often to nag
intercept/
intercept-events-flow.xml
NA webflow definition file for enumerating custom events to use as the result of custom intercept flows
  • Support a custom Event as the result of an intercept flow for error handling purposes

intercept/
profile-intercept.xml

--------------------------------------------------------

NConfigures flows that are run at various defined points inside a profile flow to modify its behavior or change its results
  • Add custom intercept flows developed locally
  • Duplicate built-in flows to allow for specialized versions