AgentResolverBasics

Overview

This is an introduction to how to use the Hub’s Agent Resolver service for simple/routine usage that omits the more advanced features and capabilities of the service. A more in-depth summary of its capabilities can be found in AgentResolverService.

The default configuration file for this service is conf/sp/agents.xml. The Agent Resolver service is an additional ReloadableService added by the Hub alongside the ones already supplied with the IdP (metadata, attribute services, etc.), so you may periodically or manually reload the service when altering the file using the service ID shibboleth.sp.AgentResolver (or configure relevant properties so it detects changes automatically of course, as with other services).

The service’s configuration design has been heavily “biased” in favor of supporting a set of simple use cases as the advisable approach for deploying a Hub and Agents. That is, if you follow the advice and approach outlined in this topic, things should stay relatively simple and clean, and the effort to deploy new Agents will be minimized.

As such, this is not really an overview of the actual structure of the service and how it can be used because there is a lot of flexibility omitted from this overview. The flexibility comes at a significant cost in complexity.

Much of the default file is commented, illustrating there are a number of optional aspects to using the configuration. Much of the behavior is automated such that installing protocol plugins such as those provided for SAML and OpenID support will automatically register a lot of runtime objects to enable support for those protocols without requiring you to manually add them to the configuration. This, combined with the prevalence of various global properties, allow a Hub to be easily configured such that all its Agents act in a similar manner without a lot of XML being added to the file.

Agents

The primary thing you will always have to do is to add a bean for each Agent (in the logical sense) you need to support. By logical, we mean that a collection of installed Agents acting as part of a single (perhaps clustered or load balanced) service/site typically only needs to be defined once as a single Agent. The Hub is designed to serve multiple non-overlapping collections of Agents, and this is typically why adding new beans will be necessary.

The bare minimum required to add a new logical Agent is to add a bean using the parent shibboleth.sp.Agent, as shown in the delivered file. There are usually only three other bean properties one needs to add, though of course many others are supported:

• p:id – this is the Agent ID, which uniquely identifies all Agents supported by a Hub

  • Hub operators should curate and supply these names to Agent deployers, typically in a manner that is consistent with other naming conventions applied to related values such as the p:issuer property.

  • Note that the p:id syntax is somewhat optional (idwill usually work), but using the prefixed form allows an Agent ID to technically violate any of Spring’s normal rules for the syntax of a bean ID; with this form essentially any String will work, allowing a bit more flexibility in naming.

• p:issuer – this establishes a protocol-level identifier for the system (e.g., SAML entityID or OpenID client_id)

  • This property defaults to the value of the sp.issuer property (conf/sp/sp.properties) but when multiple Agents are supported, a single value won’t suffice, so each new Agent bean needs its own value (usually anyway).

  • This value is intended to be very stable and change only very rarely because changing it impacts every authenticating authority used by the Agent. In particular, changing this value invalidates any existing set of “pairwise” identifiers of various sorts that SAML and OpenID both support, so unless you intend to rekey your entire application, you’d best either never change this value, or avoid pairwise identifiers altogether.

• p:credentials or p:usernames – one of these is required if the Hub is to be remotely accessed by its Agents, to control how these requests are secured

  • This is needed if/when supporting multiple Agents that are likely to be remote from the Hub and is demonstrated in more detail in the SecuringAgentConnections topic.

• p:authority – this specifies the IdP/OP/etc. that the Agent intends to issue requests to

  • This property defaults to the value of the sp.defaultAuthority property (conf/sp/sp.properties) but may be set by Agent/Application.

  • May be omitted only when IdP Discovery is in use and relevant settings are in place for that.

Putting this together, adding an Agent definition for a site hosting an HR system might look like the following, allowing that Java properties could be used for some of these settings if only a single Agent is to be supported:

Profiles and Profile Configurations

Each Agent supports a set of features exposed by the Hub called “profiles”, which is a term borrowed from SAML that just means “all the rules that make up a use case within a broader standard”. Browser SSO is an example of (the most common) SAML profile, and Single Logout would be another. OpenID Connect includes its own similar set of profiles, including some unusual ones that operate publically to provide configuration metadata to OPs.

Shibboleth represents each profile with a bean that implements various interfaces that collectively expose all of the settings that can be tweaked to alter the system’s behavior when a particular profile runs. With the Hub operating as intended, profiles are automatically enabled when a plugin that supplies them is installed. You don’t see them to keep the file simpler and to avoid the need to manually add them to start using the software.

The default settings used by a profile are carefully planned to reflect what we see as best practices, in an attempt to limit the amount of tweaking required. In particular, these settings should always work well when using the Shibboleth IdP software as an authority for the Hub’s Agents if its behavior isn’t altered significantly.

Our intention is that if/when these settings are altered, that you do so globally when possible, and we provide various properties across a set of property files to do so without requiring new XML. At the same time, we also provide mechanisms (currently limited to SAML metadata but hopefully expanding in the future) to override particular settings using metadata extension “tags”. (Pending SP specific material, refer to the MetadataDrivenConfiguration topic in the IdP documentation.) This allows settings to be tweaked when interacting with a particular authority when necessary.

In rarer cases, you may also fully override the internal Profile Configuration bean for any given profile, but when doing so, you will have to add all profiles you want to support, at least by reference, not just one you are intending to alter. The commented beans near the end of the delivered file are used to define two lists of these beans:

• shibboleth.sp.DefaultProfileConfigurations – these are profiles that rely on access to trusted information (such as SAML Metadata) to recognize and interact with authorities, such as SSO and Logout

• shibboleth.sp.UnverifiedProfileConfigurations – these are profiles that typically supply public information to clients, and are commonly used with OpenID, and less so with SAML; the term “unverified” is in reference to the fact that no trust information is expected to be on hand and in fact the access to the feature may not even self-identify as coming from a particular peer, such as an anonymous HTTP GET request

For specifics on what would be added to those lists, and why you might want to, refer to these protocol-specific topics:

• SAML

• OpenID Connect

Relying Party Overrides

The other bean defined in agents.xml, shibboleth.sp.RelyingPartyOverrides, is uncommented but empty. This is a container for any RelyingParty overrides you choose to define. This is a concept borrowed from the IdP (and indeed the older SP) and allows behavioral changes to be targeted at specific peers. In the SP’s case, a peer relying party is an authority service (an IdP, OP, etc.).

This mechanism is largely supplanted now by the MetadataDrivenConfiguration feature noted in the previous section; it is advisable to use tags to override settings rather than defining XML “inside” the configuration because metadata is more flexible and often more concise. Nevertheless it is still possible to define overrides.

An override is a bean that conceptually defines under what conditions it applies and then carries settings and/or profile configuration beans that contain desired non-default settings to use when interacting with the relying parties that trigger the override. Overrides exist as a sequence and the first override that applies is used in whole, with no regard for the content of any previous or later override beans.

A degree of inheritance exists such that if you do not supply a value for a particular property, the setting derived from the “default” RelyingPartyConfiguration is used, and that means the settings defined on the active Application bean associated with a request. For the moment, this is a distinction from the IdP’s RelyingParty configuration service, which does not support any notion of inheritance in general.

This topic will not go into further detail about overrides, but you can refer to DefiningRelyingPartyConfigurations (particularly the later sections) for more on this.