ApplicationSettingsReference

Location: conf/sp/agents.xml, conf/sp/sp.properties

This is a summary of the settings supported on the Application Java interface. With a few outliers, this interface primarily addresses two needs:

exposing various system services for use when processing requests for the corresponding Applicaton
acting as a “resolver” of RelyingPartyConfigurations, which are the primary container of settings used at runtime to control SAML, OpenID, etc. behavior

While the javadoc is ultimately the formal reference, each supported setting is described in more detail here along with any caveats around their use.

Some of the supported settings include both static and dynamic setters. When a dynamic option exists, it will accept a Java Function or Predicate to act as a “strategy” to execute at runtime to compute the relevant setting instead of relying on a static value. The corresponding setting name and type are in the tables below.

Note that all Agent beans implicitly support the Application interface also, so all of these settings may be defined on Agent beans as well.

There are two parent beans supplied for defining non-default Application beans in the AgentResolverServiceconfiguration:

shibboleth.sp.Application
shibboleth.sp.Application.NoInheritance

Most often the former should be used; the latter prevents an Application Override from inheriting various settings from its Agent parent.

In either case, these beans would be defined inside a <set> bean, to be used as the value of one (and only one) Agent bean’s applications property.

[ 1 id ] [ 2 authenticatingAuthority ] [ 3 discoveryService ] [ 4 stateTokenManager ] [ 5 sessionInitiators ] [ 6 tokenConsumers ] [ 7 logoutInitiators ] [ 8 logoutConsumers ]

id

Type:

String

Default:

None, but is required

This setting assigns a unique identifier to each Application. All Agents must be uniquely identified within an Agent (but may overlap across distinct Agents). By convention, partly for legacy reasons, the Application exposed by each Agent as a default is actually identified as “default”, so that exact value is not permitted.

It is an option to set this property using the p:id syntax rather than idto avoid the setting being enforced as a valid Spring bean ID, as that will allow a wider range of legal Application IDs.

This example sets the ID for an Application override installed into an Agent:

<bean p:id="hr.example.org" parent="shibboleth.sp.Agent">
  <property name="applications">
    <set>
      <bean p:id="admin" parent="shibboleth.sp.Application" />
    </set>
  </property>
</bean>

authenticatingAuthority

Type:

String

Default:

%{sp.defaultAuthority}

Dynamic Variant:

authenticatingAuthorityLookupStrategy

Dynamic Type:

Function<ProfileRequestContext,String>

Controls which authenticating authority (a generic term of art) to use for requests to this Application. In SAML, this would be the IdP’s entityID while in OpenID, this is would be the OP’s issuer value, etc.

The default value of this bean property is controlled by the Java property named sp.defaultAuthority (usually in conf/sp/sp.properties); this property is set to a dummy value by default and is typically adjusted when initially deploying a Hub used in enterprise, single authority deployments.

If this setting is absent, then typically the discoveryService setting must be set (directly or via Java property) in order for authentication requests to be generated by the Hub.

It is NOT advisable to define an Application Override for the purposes of overriding this value, as it can be controlled from the Agent if necessary, or it can be computed with a lookup strategy for more dynamic use cases in which the value may depend on value(s) found in the Agent request.

This example sets the authority on an Agent (illustrating that the Agent bean supports all the settings defined for Application beans):

<bean p:id="hr.example.org" parent="shibboleth.sp.Agent" p:authenticatingAuthority="https://idp.example.org/idp" />

It is possible to set this property to a null value (in Spring, this can be done with the value “#{null}”) in an ApplicationOverride, though of course a discoveryService setting is required to be in place.

This example relies on the default property to establish an Agent’s authority value, while an Application Override sets it to a null value to permit discovery:

<bean p:id="hr.example.org" parent="shibboleth.sp.Agent">
  <property name="applications">
    <bean p:id="guests" parent="shibboleth.sp.Application"
        p:authenticatingAuthority="#{null}"
        p:discoveryService="https://ds.example.org/DS" />
  </property>
</bean>

discoveryService

Type:

String

Default:

%{sp.discoveryURL}

Dynamic Variant:

discoveryServiceLookupStrategy

Dynamic Type:

Function<ProfileRequestContext,String>

Provides the location to a standardized Identity Provider Discovery Service to use in the absence of an authenticatingAuthority setting. If set, this is the “base” URL of the Discovery Service to use in the event that during a request for authentication, the Hub can’t identify a way to generate one, falling into the “last resort” of redirecting to a DS.

The default value of this bean property is controlled by a pair of Java properties (usually in conf/sp/sp.properties), evaluated in order:

sp.discoveryURL
- If this property is set, this is the default value of the setting.
sp.discoveryURLFunction
- If this property is set, the value is used as the bean ID for the discoveryServiceLookupStrategy setting.

The two Java properties thus allow global determination of a DS to use, either statically or dynamically, while it is also possible to define either setting explicitly per-Agent/Application.

If this setting is absent, then typically the authenticatingAuthority setting must be set (directly or via Java property) in order for authentication requests to be generated by the Hub.

This example sets the DS in an override while “unsetting” the authenticatingAuthority setting that may be defaulted elsewhere:

<bean p:id="hr.example.org" parent="shibboleth.sp.Agent">
  <property name="applications">
    <set>
      <bean p:id="federated" parent="shibboleth.sp.Application"
        p:authenticatingAuthority="#{null}"
        p:discoveryService="https://ds.example.org/DS" />
    </set>
  </property>
</bean>

stateTokenManager

Type:

StateTokenManager

Default:

%{sp.stateToken.Manager}

Controls the component used to record state information when issuing authentication requests for recovery when processing responses later. The specific information recorded varies by protocol and the details are left to implementations of the StateTokenManager interface. This allows Agents or Applications to tailor the implementation used.

The default value of this bean property is the Spring bean identified by the Java property sp.stateToken.Manager (usually in conf/sp/sp.properties). The system ships with the following predefined implementation beans:

shibboleth.sp.StorageStateTokenManager – implementation that uses a StorageService identified by the sp.stateToken.StorageService Java property
shibboleth.sp.CookieStateTokenManager – implementation that uses protected cookies tailored by various Java properties

Currentlly the former is the default, but this is only suitable when the Hub is not clustered or when an external StorageService is defined. This default may change before the final release.

This example installs an alternate implementation bean for (only) a particular Agent (illustrating that the Agent bean supports all the settings defined for Application beans):

<bean p:id="hr.example.org" parent="shibboleth.sp.Agent" p:stateTokenManager-ref="shibboleth.sp.CookieStateTokenManager" />

Note that unlike most examples with “simple” types, installing components typically is done by reference, with -ref added to the end of the property name to indicate that the value is a Spring bean ID.

sessionInitiators

Type:

List<String>

Default:

Plugin-controlled

Dynamic Variant:

sessionInitiatorsLookupStrategy

Dynamic Type:

Function<ProfileRequestContext<List<String>>

Controls the sequence of Session Initiator flows to attempt in handling Agent requests to issue a new authentication request. “Session Initiator” is a term of art within both the Agent and Hub that dates to the older SP software and refers to the functionality responsible for “initiating” a new session by issuing a request for authentication. Protocol plugins implement one or more such flows and contribute them to the runtime when installed into the Hub. The SAML plugin supplies flows that produce SAML <AuthnRequest> messages via various bindings, while the OIDC plugin supplies flows that produce OIDC authorization requests in a variety of ways.

By default, and sufficient for most cases, these flows are registered at runtime and installed in a particular order automatically and the system will attempt them all in sequence. If metadata or client information for the configured authority allows one of them to run, then a request is generated and the process completes. If they all fail, then either Discovery is attempted (if configured), or the request from the Agent fails.

This setting provides a means of customizing the set of flows that will be run for a particular Agent/Application. This would normally be done as a means of controlling order if it were known that a particular protocol or binding/format were required for the use case.

See TBD for a complete plugin-specific summary of the flows available and how to control the order both externally and with this setting. When using this setting, the value is a list of the flow IDs to run in the desired order.

tokenConsumers

Type:

List<String>

Default:

Plugin-controlled

Dynamic Variant:

tokenConsumersLookupStrategy

Dynamic Type:

Function<ProfileRequestContext<List<String>>

Controls the sequence of Token Consumer flows to attempt in handling Agent requests to process authentication responses. “Token Consumer” is a term of art within both the Agent and Hub and refers to the functionality responsible for consuming authentication tokens such as SAML assertions or OpenID tokens. Protocol plugins implement one or more such flows and contribute them to the runtime when installed into the Hub. The SAML plugin supplies flows that consume SAML <Response> messages via various bindings, while the OIDC plugin supplies flows that consume OIDC authorization responses, codes, etc. in a variety of ways.

By default, and sufficient for most cases, these flows are registered at runtime and installed in a particular order automatically and the system will attempt them all in sequence. If metadata or client information for the configured authority allows one of them to run, then the response is processed or an error is returned to the Agent.

This setting provides a means of customizing the set of flows that will be run for a particular Agent/Application. This would normally be done as a means of controlling order if it were known that a particular protocol or binding/format were required for the use case. As a rule, these flows only run if they detect that they are the proper flow to handle the message they see, so controlling the order is rarely essential but is an optimization.

See TBD for a complete plugin-specific summary of the flows available and how to control the order both externally and with this setting. When using this setting, the value is a list of the flow IDs to run in the desired order.

logoutInitiators

Type:

List<String>

Default:

Plugin-controlled

Dynamic Variant:

logoutInitiatorsLookupStrategy

Dynamic Type:

Function<ProfileRequestContext<List<String>>

Controls the sequence of Logout Initiator flows to attempt in handling Agent requests to issue a new “single logout” request. “Logout Initiator” is a term of art within both the Agent and Hub that dates to the older SP software and refers to the functionality responsible for “initiating” a logout operation by handling things locally and then optionally issuing a logout request message to the “session authority”.

Protocol plugins implement one or more such flows and contribute them to the runtime when installed into the Hub. The SAML plugin supplies flows that produce SAML <LogoutRequest> messages via various bindings, while the OIDC plugin supplies flows that produce OIDC logout requests in a variety of ways. Note that these plugins support only “front-channel” logout approaches.

By default, and sufficient for most cases, these flows are registered at runtime and installed in a particular order automatically and the system will attempt them all in sequence. If metadata or client information for the configured authority allows one of them to run, then a request is generated and the process completes. If they all fail, then the Agent receives a response it can use to identify this case and simply complete the local logout process by redirecting to a desired resource.

This setting provides a means of customizing the set of flows that will be run for a particular Agent/Application. This would normally be done as a means of controlling order if it were known that a particular protocol or binding/format were required for the use case.

See TBD for a complete plugin-specific summary of the flows available and how to control the order both externally and with this setting. When using this setting, the value is a list of the flow IDs to run in the desired order.

logoutConsumers

Type:

List<String>

Default:

Plugin-controlled

Dynamic Variant:

logoutConsumersLookupStrategy

Dynamic Type:

Function<ProfileRequestContext<List<String>>

Controls the sequence of Logout Consumer flows to attempt in handling Agent requests containing possible “single logout” requests or responses from authorities. “Logout Consumer” is a term of art within both the Agent and Hub, new with this release, that refers to the functionality responsibility for processing logout requests and issuing logout responses.

Protocol plugins implement one or more such flows and contribute them to the runtime when installed into the Hub. The SAML plugin supplies flows that handle SAML <LogoutRequest> and <LogoutResponse> messages via various bindings, while the OIDC plugin supplies flows that produce OIDC logout requests and responses in a variety of ways. Note that these plugins support only “front-channel” logout approaches.

By default, and sufficient for most cases, these flows are registered at runtime and installed in a particular order automatically and the system will attempt them all in sequence. If none are able to handle the Agent request, or if the selected flow fails, the Agent regains control and has the ability to react in whatever manner it chooses (including optionally completing logout locally, or not).

This setting provides a means of customizing the set of flows that will be run for a particular Agent/Application. This would normally be done as a means of controlling order if it were known that a particular protocol or binding/format were required for the use case.

See TBD for a complete plugin-specific summary of the flows available and how to control the order both externally and with this setting. When using this setting, the value is a list of the flow IDs to run in the desired order.