ConfigurationFileSummary

The configuration file count is very large, partly due to supporting so many features, partly because we have created smaller units of configuration dealing with specific tasks, and partly because we've tried to expose a lot of 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.

Many other files may optionally exist, but are only installed when particular modules are enabled and will be described in the relevant topics.

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.

File

RL?

Purpose

 Tasks

File

RL?

Purpose

 Tasks

access-control.xml

Y

Controls access to administrative functions like the status page, resolver testing tool, service reloading, etc

  • Changing IP address restrictions on access to "admin" URLs

  • Defining rules for certain features such as impersonation

attribute-filter.xml

Y

Attribute release policy controlling whether to return attributes to a requester or accept them from an issuer

  • Controlling the SAML Attributes provided to SPs during SSO or via a Query

  • Limiting acceptance of SAML Attributes from a proxied IdP

attribute-registry.xml

Y

A new service for configuring mapping rules for converting between SAML/OIDC/CAS attributes and internal IdPAttribute definitions

  • Customizing the location(s) from which to load mapping rules

attribute-resolver.xml

Y

How 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

  • Controlling pass-through or modification of proxied information

audit.xml

N

Controls general audit log behavior

  • Add or change audit log entry formats

  • Add a custom audit field with Java or scripting

credentials.xml

Y

Configure private keys and certificates.

  • Add additional signing or encryption keypairs

  • Enable a second encryption key during a key rollover

errors.xml

N

Error 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.xml

N

A 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.properties

N

Java property file used to change common or important settings more easily

  • 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.properties

N

Java 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

logback.xml

Y

Logback logging configuration

  • Change unusual logging levels, locations, file retention behavior

  • Add custom log destinations (e.g., syslog)

metadata-providers.xml

Y

Configure sources of SAML metadata

  • Add metadata sources

  • Control metadata verification and filtering

mvc-beans.xml

N

A place to put custom bean definitions for the Spring MVC layer, not created 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.xml

Y

Controls 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 requiring metadata for SPs

saml-nameid.properties

N

Java 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

  • Change default NameID formats

saml-nameid.xml

Y

Controls support for and generation/sourcing of SAML NameIDs

  • Turn on or off transient and persistent identifier support

  • Configure custom NameIDs based on resolved attributes

credentials/secrets.properties

N

Parking lot for any properties of a secret nature that should not be checked into configuration management tools

  • Setting various passwords present in a default install

  • Adding additional passwords in the future

services.properties

N

Java 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.xml

N

Controls 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

admin/admin.properties

N

Customization of administrative flows (replaces most of the need for general-admin.xml in previous versions)

  • Customize flow settings such as authentication or access control rules

admin/metrics.xml

N

Configures customizable instrumentation and reporting features

  • Enable or disable metrics

  • Configure metric reporting features

  • Enable customized timers or counters

attributes/default-rules.xml
(and various schema-specific rule files)

Y

Default mapping rules for "conventional" attributes in common or standard usage

  • Change default mappings

  • Add or update language translations

attributes/custom/                             

N

A directory in which property-based attribute mapping rules can be dropped for local customization

  • Add your own attribute mapping rules using property syntax

authn/authn-comparison.xml

N

Establish 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

  • Map SAML AuthnContext values while proxying

authn/authn-events-flow.xml

N

A 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 or as flow control within the MFA feature

authn/authn.properties

N

Customization of authentication flows (replaces most of the need for general-authn.xml and many of the other authn-related XML files in previous versions)

  • Customize authn settings such as timeouts, and support for SAML AuthnContext classes for controlling login method selection

c14n/subject-c14n-events-flow.xml

N

A 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.properties

N

Controls most simple settings of particular post-login c14n methods (replaces most of the need for c14n-related XML files in previous versions)

  • Apply transforms to usernames after login

  • Control mapping of username through attribute resolution

  • Control username extraction from X.509 certificates

c14n/subject-c14n.xml

N

Configures order of mechanisms for processing usernames after authentication, and for mapping SAML NameID values back into usernames

  • Change how usernames are transformed after login

  • Support Attribute Queries or other advanced SAML features based on custom identifier types

intercept/intercept-events-flow.xml

N

A 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