File(s): conf/services.xml, conf/services.properties
Format: Native Spring
Overview
The services.xml file is used to specify many of the other configuration files (or more generally, Spring Resources) to load to configure various important services within the IdP. The services.properties file provides a less granular way to identify the Spring beans containing the lists of resources, and also controls the dynamic reloading behavior of those services.
You might modify these files to:
change the resources used, or more commonly add additional resources to supplement built-in defaults
configure more specialized approaches such as remote HTTP resources (though there are limited security controls available for this)
control how often to check for changes and reload configurations, if at all
The services.xml file contains a series of "list" beans that specify the Spring Resources to load into various services. The lists are named with specific bean IDs (see below) that direct the resources into the various services. If you wish to supply your own resource lists without modifying the delivered lists, you may control the bean IDs used by modifying services.properties.
You can use any kind of Resource supported by Spring, along with additional custom resource types provided with the IdP for handling HTTP and other custom resources.
Resources provided by the project include the HTTPResource and the RunnableFileSystemResource
Fail Fast
The fail-fast behavior, which can be adjusted by service to a limited degree, determines whether the IdP webapp context will initialize and serve clients if a particular service fails to initialize successfully. The point of this mechanism is to allow you to decide for yourself when problems should be discovered and how serious they should be treated. While it isn't the default, you may find it simpler when first starting out to enable fail-fast behavior globally while you work through mistakes.
Whether a given service succeeds or fails is ultimately an internal consideration, but generally we're talking about whether its configuration is valid and whether its pieces and parts themselves are considered to be successfully initialized. Often there may be individual fail-fast settings applying at the micro level that in turn dictate whether the surrounding service starts (and which then determines the overall result of the IdP startup process based on the service's fail-fast behavior). On top of that, some of the subsystems cause ripple effects when they fail that may make it impossible to really achieve non-fail-fast behavior in some cases.
There are two levels of fail-fast properties that control service behavior (and described below). A global property called idp.service.failFast can be used to toggle all services to fail-fast at once (since the default is false for most, but true for a couple). In addition, or instead, you can control the behavior of specific services with properties specific to each service. The individual properties override the global setting, so you can mix and match.
Reloading Services
In addition to the "checkInterval" properties listed below to automatically reload services, you may reload a service at any time using the reload-service command line utility and the service ID. The service IDs are shown below in the Beans table (excluding the logging service, which is "shibboleth.LoggingService").
$ ./reload-service.sh -id shibboleth.AttributeResolverService
Alternatively, you may reload services by issuing a GET request to the following URL, assuming your client has access as defined in AccessControlConfiguration.
GET http(s)://[idp-base-url]/idp/profile/admin/reload-service?id=shibboleth.LoggingService
Reference
Properties
Properties defined in services.properties follow:
Property / Type / Default | Description |
|---|
idp.service.failFast Boolean false | Set default fail-fast behavior of all services unless overridden by service |
idp.service.logging.resource Resource path %{idp.home}/conf/logback.xml | Logging configuration resource to use (the reloadable service ID is "shibboleth.LoggingService") |
idp.service.logging.failFast Boolean true | Fail at startup if logging configuration is invalid |
idp.service.logging.checkInterval Duration 0 | Time to notice changes to logging configuration and reload service.
A value of 0 indicates that the logging configuration never reloads |
idp.service.relyingparty.resources Bean ID shibboleth.RelyingPartyResolverResources | Name of Spring bean identifying resources to use for RelyingPartyConfiguration |
idp.service.relyingparty.failFast Boolean false | Fail at startup if RelyingPartyConfiguration is invalid |
idp.service.relyingparty.checkInterval Duration 0 | Time to notice changes to RelyingPartyConfiguration and reload service
A value of 0 indicates that the relying party configuration never reloads |
idp.service.relyingparty.ignoreUnmappedEntityAttributes Boolean false | See MetadataDrivenConfiguration, SAML Attribute Name Format Usage |
idp.service.metadata.resources Bean ID shibboleth.MetadataResolverResources | Name of Spring bean identifying resources to use for MetadataConfiguration |
idp.service.metadata.failFast Boolean false | Fail at startup if MetadataConfiguration is invalid |
idp.service.metadata.checkInterval Duration 0 | Time to notice changes to MetadataConfiguration and reload service
A value of 0 indicates that the metadata configuration never reloads |
idp.service.metadata.enableByReferenceFilters Boolean true | Disabling this turns off internal support for the ByReferenceFilter feature, which provides a very small performance boost |
idp.service.attribute.registry.resources Bean ID shibboleth.AttributeRegistryResources | Name of Spring bean identifying resources to use for AttributeRegistryConfiguration |
idp.service.attribute.registry.failFast Boolean false | Fail at startup if AttributeRegistryConfiguration is invalid |
idp.service.attribute.registry.checkInterval Duration 0 | Time to notice changes to AttributeRegistryConfiguration and reload service. A value of 0 indicates that the service configuration never reloads |
idp.service.attribute.registry.encodeType Boolean true | Shortcut for controlling the encoding of xsi:type information for all SAML transcoding rules in the registry |
idp.service.attribute.resolver.resources Bean ID shibboleth.AttributeResolverResources | Name of Spring bean identifying resources to use for AttributeResolverConfiguration |
idp.service.attribute.resolver.failFast Boolean false | Fail at startup if AttributeResolverConfiguration is invalid |
idp.service.attribute.resolver.checkInterval Duration 0 | Time to notice changes to AttributeResolverConfiguration and reload service. A value of 0 indicates that the service configuration never reloads |
idp.service.attribute.resolver.maskFailures Boolean true
| Whether attribute resolution failure should silently produce no attributes. or cause an overall profile request failure event |
idp.service.attribute.resolver.stripNulls Boolean false
| Whether null values should be stripped from the results of the attribute resolution.
This filtering happens prior to filtering and encoding, but after attribute resolution is complete.
To strip nulls during attribute resolution (so that they will be invisible to dependant attribute definitions) use
a SimpleAttributeDefinition and specify ignoreNullValues |
idp.service.attribute.resolver.suppressDisplayInfo 4.2 Boolean true | Setting this to false re-enables the legacy behavior of looking up the display information for the resolved attributes during resolution.
As from 4.2 this the display information is looked up at point of use (during the attribute consent flow) and so there should be no reason to revert this behavior unless using third party software which expect the IdPAttribute DisplayName and DisplayDescriptions to be pre-populated |
idp.service.attribute.filter.resources Bean ID shibboleth.AttributeFilterResources | Name of Spring bean identifying resources to use for AttributeFilterConfiguration |
idp.service.attribute.filter.failFast Boolean false | Fail at startup if AttributeFilterConfiguration is invalid |
idp.service.attribute.filter.checkInterval Duration 0 | Time to notice changes to AttributeFilterConfiguration and reload service
A value of 0 indicates that the attribute filter configuration never reloads |
idp.service.attribute.filter.maskFailures Boolean true | Whether attribute filtering failure should silently produce no attributes or causes an overall profile request failure event |
idp.service.nameidGeneration.resources Bean ID shibboleth.NameIdentifierGenerationResources | Name of Spring bean identifying resources to use for NameIDGenerationConfiguration |
idp.service.nameidGeneration.failFast Boolean false | Fail at startup if NameIDGenerationConfiguration is invalid |
idp.service.nameidGeneration.checkInterval Duration 0 | Time to notice changes to NameIDGenerationConfiguration and reload service |
idp.service.access.resources Bean ID shibboleth.AccessControlResources | Name of Spring bean identifying resources to use for AccessControlConfiguration |
idp.service.access.failFast Boolean true | Fail at startup if AccessControlConfiguration is invalid |
idp.service.access.checkInterval Duration 0 | Time to notice changes to AccessControlConfiguration and reload service |
idp.service.cas.registry.resources Bean ID shibboleth.CASServiceRegistryResources | Name of Spring bean identifying resources to use for CASServiceRegistry configuration |
idp.service.cas.registry.failFast Boolean false
| Fail at startup if CASServiceRegistry configuration is invalid |
idp.service.cas.registry.checkInterval Duration 0 | Time to notice CASServiceRegistry configuration changes and reload service |
idp.service.managedBean.resources Bean ID shibboleth.ManagedBeanResources | Name of Spring bean identifying resources to use for ManagedBeanConfiguration |
idp.service.managedBean.failFast Boolean false | Fail at startup if ManagedBeanConfiguration is invalid |
idp.service.managedBean.checkInterval Duration 0 | Time to notice ManagedBeanConfiguration changes and reload service |
idp.message.resources Bean ID shibboleth.MessageSourceResources | Name of Spring bean identifying Spring message property resources |
idp.message.cacheSeconds Integer 300 | Seconds between reloads of message property resources |
Beans
Beans defined via services.xml follow: