This software is not yet released and this is preliminary documentaton subject to significant change. It should not be used in production or to protect important resources at this stage.
AgentSettingsReference
Location: conf/sp/agents.xml, conf/sp/sp.properties
This is a summary of the settings supported on the Agent Java interface, which mostly pertain to how to validate connections from it and to navigate to the rest of the settings defined at lower levels of the design. While the javadoc is ultimately the formal reference, each supported setting is described in more detail here along with any caveats around their use.
The shibboleth.sp.Agent bean is a parent bean for defining new Agent beans in the AgentResolverService configuration. You must always use that parent bean when defining additional Agents to the Hub:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" />id
Type: String | Default: None, but is required |
This setting assigns a unique identifier to each Agent. All Agents must be uniquely identified within a Hub deployment. The Agent ID can act as a “username” for Agent authentication to the Hub, but Agents may be configured with multiple, alternative (but still unique) usernames via the credentials and usernames settings.
An Agent ID may contain any characters except for the '!' (bang/exclamation mark) character.
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 Agent IDs.
This example sets the ID for an Agent used in an HR application:
<bean p:id="hr.example.org" parent="shibboleth.sp.Agent" />allowedAddressRanges
Type: Set<IPRange> | Default: %{sp.agent.authn.allowedAddressRanges} |
Controls the IP address(es) permitted for connections from this Agent. A request containing this Agent’s ID is checked against this value before permitting additional processing to occur (this is one of the earliest and fastest checks the Hub can apply).
The default value of this bean property is controlled by the Java property named sp.agent.authn.allowedAddressRanges (usually in conf/sp/sp.properties); this property is set to limit connections to the same host by default.
The value is a Set of IPRange objects, but support for String to IPRange conversion is built-in to the IdP, so Strings are normally used in the form of a CIDR network range expression. These expressions may be in IPv4 or IPv6 syntax.
Limiting connections to a single address typically requires an expression ending in “/32” or “/128” for IPv4 or IPv6 respectively. Conversely, allowing connections from any address would require “0.0.0.0/0” and/or “::/0”.
This example is equivalent to the default value shipped with the software:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:allowedAddressRanges="#{{ '127.0.0.1/32', '::1/128' }}" />authenticationMethod
Type: String | Default: %{sp.agent.authn.method} |
Controls the method used to authenticate Agent requests. The only supported values for this setting are “basic” and the null value, which stands for “no authentication is performed”.
The default value of this bean property is controlled by the Java property named sp.agent.authn.method (usually in conf/sp/sp.properties); this property is unset by default for support of localhost-only Agent connections.
The default of null is typically changed to “basic” when the Hub is operated in a shared capacity for remote Agents and is typically controlled via the Java property, so this setting is not commonly needed, but is mostly for future extension if other methods are ever supported.
This example sets a single Agent’s method to “basic”:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:authenticationMethod="basic" />credentials
Type: Map<String,String> | Default: Empty map |
Provides an “inline” Map of username/password pairs that the Agent may use to authenticate to the Hub.
This feature is primarily for testing or smaller-scale deployments, as it would not be typical to embed secrets directly into the configuration. A more typical approach is to use the username setting instead, with a more robust authentication service (LDAP, Kerberos, etc.).
This is discussed in more depth in the SecuringAgentConnectionstopic.
Either the key or value (but not both) may be nulls. A null key signifies that the Agent’s id property is used as the username component. A null password means that the key is installed as a valid “username” for the Agent but with no “internal” password. This username may be used when an external secret validation component is in use to validate the password at runtime.
Because an Agent may use these values to identify itself to the Hub, all usernames (the map keys) MUST be unique across all Agents for a given Hub, just as the Agent id property is assumed to be unique. That is, a given value used in a request must uniquely map to one and only one Agent in the configuration.
Consider the case where an LDAP directory is configured to validate the username/password pair of “foo” / ”bar”. In the folliowing example, each of these username/password pairs would be valid:
“foo” / “bar”
“agent.example.org” / “bar”
“SA-example1” / “zork”
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:credentials="#{{ 'foo':null, null:'bar', 'SA-example1':'zork' }}" />usernames
Type: Collection<String> | Default: Empty collection |
Configures a collection of valid usernames the Agent may use when authenticating to the Hub. Absent this setting, the Agent’s id property is the only value accepted. As no passwords/secrets are provided, this setting is used in conjunction with enterprise-level authentication options (LDAP, Kerberos, etc.).
Because an Agent may use this value to identify itself to the Hub, all usernames MUST be unique across all Agents for a given Hub, just as the Agent id property is assumed to be unique. That is, a given value used in a request must uniquely map to one and only one Agent in the configuration.
This feature is useful to create “indirection” between the Agent’s identifier and the valid account names with which it may authenticate. Specifying multiple usernames is useful to support Agent service account rollover, as required by some organizations.
This is discussed in more depth in the SecuringAgentConnectionstopic.
This setting is equivalent to providing mappings via the credentials property in which the map keys correspond to this setting’s values, while the map values are all null.
This example installs a pair of service account usernames for an Agent:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:usernames="#{{ 'SA-example1', 'SA-example2' }}" />supportsCachedAuthentication
Type: Boolean | Default: %{sp.agent.authn.cached} |
This setting controls the use of an HTTP cookie to maintain a session with the Agent so that subsequent requests with the same cookie will bypass authentication for a period of time.
The default value of this bean property is controlled by the Java property named sp.agent.authn.cached (usually in conf/sp/sp.properties); this property is true by default.
This example disables cached authentication for a single Agent:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:supportsCachedAuthentication="false" />supportsPostPreservation
Type: Boolean | Default: %{sp.postData.preservation} |
This setting controls the ability of the Agent to pass POST data to the Hub for preservation during an authentication round trip. This is discussed in more depth in the FormPOSTRecoverytopic.
The default value of this bean property is controlled by the Java property named sp.postData.preservation (usually in conf/sp/sp.properties); this property is false by default.
This example enables POST recovery for a single Agent:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:supportsPostPreservation="true" />postLimit
Type: Long | Default: %{sp.postData.limit} |
This setting controls the maximum amount of POST data (in bytes) the Hub will preserve for the Agent during an authentication round trip. This is discussed in more depth in the FormPOSTRecoverytopic. The setting is ignored if the supportsPostPreservation setting is false.
The default value of this bean property is controlled by the Java property named sp.postData.limit (usually in conf/sp/sp.properties); the default is 1024^2
This example enables POST recovery for a single Agent with a non-default limit:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:supportsPostPreservation="true" p:postLimit="100000" />characterEncoding
Type: String | Default: UTF-8 |
This setting controls the Character Set Encoding used to convert POST data into Java’s native String encoding when performing FormPOSTRecovery. The setting is ignored if the supportsPostPreservation setting is false.
While UTF-8 is a good default assumption, Agents operating in web servers that use a different encoding and using non-ASCII data will experience corruption if the proper encoding is not set.
This example sets a character encoding for a single Agent:
<bean p:id="agent.example.org" parent="shibboleth.sp.Agent" p:characterEncoding="ISO-8859-1" />applications
Type: Set<Application> | Default: Empty Set |
This setting allows a set of Application overrides to be defined.
The “default” Application instance for each Agent is exposed directly by the Agent bean itself, and so all the supported settings can be defined directly on the Agent bean. This setting allows additional Application beans to be injected as a Set to supply overrides the Agent may associate requests with.
Avoiding use of this feature is strongly advised.