ReloadableServices

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

Do not remove any of the beans from services.xml unless you alter a corresponding property in services.properties to direct the service to a different resource list bean, or the IdP will fail to initialize with an error referencing the missing bean.

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 defined in services.properties follow:

Property / Type / Default

Description

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.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 defined via services.xml follow:

Bean ID / Type

Description

Reloadable Service ID

Bean ID / Type

Description

Reloadable Service ID

shibboleth.RelyingPartyResolverResources

List<Resource>

RelyingPartyConfiguration resources

shibboleth.RelyingPartyResolverService

shibboleth.MetadataResolverResources

List<Resource>

MetadataConfiguration resources

shibboleth.MetadataResolverService

shibboleth.MetadataNodeProcessors

List<MetadataNodeProcessor>

Overrides the metadata NodeProcessors attached to metadata sources by default

N/A

shibboleth.AttributeRegistryResources

List<Resource>

AttributeRegistryConfiguration resources used for new installs

shibboleth.AttributeRegistryService

shibboleth.AttributeResolverResources

List<Resource>

AttributeResolverConfiguration resources

shibboleth.AttributeResolverService

shibboleth.AttributeFilterResources

List<Resource>

AttributeFilterConfiguration resources

shibboleth.AttributeFilterService

shibboleth.NameIdentifierGenerationResources

List<Resource>

NameIDGenerationConfiguration resources

shibboleth.NameIdentifierGenerationService

shibboleth.AccessControlResources

List<Resource>

AccessControlConfiguration resources

shibboleth.ReloadableAccessControlService

shibboleth.MessageSourceResources

List<Resource>

Internationalizable user interface messages

N/A

shibboleth.CASServiceRegistryResources

List<Resource>

Resources containing ServiceRegistry beans to be reloaded

shibboleth.ReloadableCASServiceRegistry

shibboleth.ManagedBeanResources

List<Resource>

ManagedBeanConfiguration resources

shibboleth.ManagedBeanService