SecuringAgentConnections

This is a high level summary and quick start to the more “advanced” ways of handliing security between Agents and the Hub and includes most of the information needed to scale out the Hub operationally.

This topic is primarily of interest to those running a shared Hub serving a distributed set of Agents typically operated by other teams. For simpler cases of a single Agent, co-located or networked, GettingStarted is a better introduction.

You should also consider reviewing HubPlanning in conjunction with your rollout.

1 Agent Secret Validation
- 1.1 Supplied Validators
- 1.2 Configuring Validation
- 1.3 Attaching Service Account Names
- 1.4 Caching
2 Address Restrictions
3 TLS Usage

Agent Secret Validation

By default, the Hub and Agents are configured without security to simplify the legacy deployment model of a colocated Agent and Hub connecting over a local backplane. Address restrictions (see below) supplement this approach.

To enable Secret Validation either set sp.agent.authn.method property (conf/sp/sp.properties) to “basic” or explictly set the authenticationMethod property on specific Agent beans to “basic”.

To operate over a network or in a multiple Agent configuration, Agents must be issued credentials in the form of an Agent ID and secret (effectively a service account) and will use HTTP Basic Authentication when making requests to the Hub. The Hub’s authentication support is based on the IdP’s CredentialValidator interface and the implementations supplied with the IdP along with one additional implementation supplied mostly for testing or very simple deployments. As with the IdP, multiple validators can optionally be implemented in series in various configurations.

While some familiarity with the IdP’s Password login flow is beneficial in understanding how this works and is configured, the documentation here does not assume that experience, but some of the existing documentation is referenced to avoid wholesale duplication.

Note that these are not full Spring Web Flows as in the IdP’s wide range of login methods, but a constrained implementation built on top of the IdP’s password valdation API. It is extensible only by providing an alternative CredentialValidator class.

Supplied Validators

Most of the validators supported out of the box are part of the IdP. The links here are to the Hub-specific documentation for them. Notably, some of the more complicated features in the IdP’s usage don’t apply to this use case, particularly around error handling, since these are strictly used in a machine to machine capacity with no user interface.

(Links TBD)

LDAP
Kerberos
JAAS
htpasswd

Internal/Spring-Based Validation

The lone additional validator specific to the Hub is the default one, which requires no separate configuration, as it allows for Agent ID/secret pairs to be embedded in an Agent bean with Spring. The bean shibboleth.sp.AgentSecretValidator implements this feature (see the next section for why you might need to reference that someday), but out of the box it’s used automatically.

This approach is used in some of the simpler examples in the GettingStarted page:

<bean p:id="sp.example.org" parent="shibboleth.sp.Agent"
  p:authenticationMethod="basic"
  p:credentials="#{ {null : 'abcdefg'} }" />

The credentials property is a map to use a “database” of ID/secret pairs to accept (the example shows one map entry in a Spring expression). This is mostly for use in testing, demos, or for the very trivial case of a Hub used with a single Agent when both are managed by the same team in a joint deployment. A separate Java property could also be used to externalize the secret, which due to Spring’s support for properties can potentially be supplied via an environment variable at container startup:

<bean p:id="sp.example.org" parent="shibboleth.sp.Agent"
  p:authenticationMethod="basic"
  p:credentials="#{ {null : '%{custom.secret}'} }" />

In these examples, the bean’s p:id property is being set to the same value as the “username” half of the credentials pair, which is signaled by using the null expression in the map keys. This is strictly optional; the username in the credential is what the Agent MUST supply to connect to the Hub, while the p:id property is how the Agent is identified in logs, auditing, and so forth within the Hub.

Configuring Validation

If, as is likely, you need to implement one of the more “robust” options for secret validation, you will need to define a list bean with the chain of validators (one or more) that you want to use. You can define this bean in the IdP’s conf/global.xml file (or feel free to create your own Hub-specific beans file and import it there). You cannot put this in agents.xml due to bean scope/visibility issues.

<!-- This bean ID is required/reserved. -->
<util:list id="shibboleth.sp.AgentValidators">
  <!-- Optionally continue to support the simple mechanism if you need it. -->
  <ref bean="shibboleth.sp.AgentSecretValidator" />
  <!-- Define your own validators... -->
  <bean parent="shibboleth.sp.LDAPValidator" />
</util:list>

Most of the core IdP features implemented for the methods noted above work the same way, but the properties (and beans in a few cases) are named differently to isolate their use from any existing use in the IdP should that ever be a consideration.

Most of the basic setup of the validators can be done through properties that are commented at the bottom of conf/sp/sp.properties. The links above for each validator will take you to the basic information you need if you can’t figure it out from context or previous IdP experience and those link further to more detailed reference material.

Attaching Service Account Names

The additional requirement to externalize Agent credentials to one or more service accounts is to attach the usernames of the accounts to the Agent bean(s) in the conf/sp/agents.xml file (or wherever they’re defined):

...
<bean p:id="sp.example.org" parent="shibboleth.sp.Agent"
  p:authenticationMethod="basic"
  p:usernames="#{{ 'SA1-sp.example.org', 'SA2-sp.example.org' }}" />
...

In the above example, a pair of service account usernames are attached to the Agent, for example to allow for account rotation. The p:usernames property is an alternative property for defining the credentials such that the secret half of each is null, which limits use to an external source of validation.

Caching

If enabled (which is the case by default), the Hub will cache a successful Agent validation for a configurable amount of time and if the Agent supplies the container session cookie in its requests, the Hub will check for a cached validation in the Java session and bypass a re-check of the secret, essentially substituting the session cookie value for the secret for the specified duration. It is optional for Agents to implement this feature but the Shibboleth-supplied Agents do support it.

The two properties controlling this on the Hub are commented in the conf/sp/sp.properties file:

# Set false to globally disable cookie-based authentication by agents
#sp.agent.authn.cached = true
#sp.agent.authn.cacheDuration = PT1H

Address Restrictions

The Hub allows a simple extra layer of protection at the connection level by validating the address from which an Agent connects against a list of CIDR network ranges (IPv4 and IPv6). This step is not optional per se, but you can leave this disabled by using the “world” ranges (0.0.0.0/0, ::/0) if desired.

The global property sp.agent.authn.allowedAddressRanges may be set to a comma-delimited list applied to all Agent connections by default if not overridden, and defaults to the loopback address ranges to allow only non-networked, local connections from an Agent on the same host, suitable for use out of the box with a single co-located Agent.

You may also attach a specific list of ranges to a particular Agent’s Spring bean definition in conf/sp/agents.xml (the example shows a couple of ranges that explicitly identify a source address):

...
<bean p:id="sp.example.org" parent="shibboleth.sp.Agent"
  p:allowedAddressRanges="{{ '192.168.0.1/32', '192.168.0.2/32' }}" />
...

TLS Usage

Securing a networked Hub requires the use of TLS to integrity protect the traffic but primarily to allow Agents to authenticate their connections to a Hub. As a Hub is a Java application running in a servlet container, it is the domain of that container or a front-end web server, load balancer, etc. to provide the HTTP-over-TLS implementation and handle the TLS key and certificate to be used. You can find examples for particular containers recommended or commonly used with the IdP in its documentation, and we also provide a Jetty plugin to simplify deployment.

Each Agent must be given one or more certificates to serve as trust anchors to validate the Hub’s certificate in the traditional fashion. As there is no way to change these trust roots other than by touching each Agent (made easier of course using deployment management tools of various kinds), it is important to limit the probability that they will need to change. But Agents must also ensure that they configure trust anchors that they truly believe will not issue a certificate to a system without control of the hub’s hostname.

While commercial certificates are necessary for an IdP deployment, they are not at all necessary or likely even advisable for a Hub unless for some reason a Hub absolutely must be co-located with an actual IdP. If you are comfortable using commercial certificates, then you certainly may do so, but might want to consider whether a trust anchor lower in the hierarchy (an intermediate perhaps) might be viable, as the lower in the chain you can go, the more secure the connections will typically be, as it reduces the number of CAs that must be trusted not to misbehave.

Usually a locally administered PKI using simple tools is a good solution to this problem. Note that the number of Hubs (particularly with different public hostnames) is usually quite limited; you are not issuing certificates to the Agents here, only to the Hub. The Agents will rely on your choice of trust anchor only.

Ultimately the goal is to balance security with the risk of having to update the trust anchor of every Agent in your environment, which could be quite large if existing SP deployment scale is a guide. The last thing you want to do is tie the Agents to a commercial certificate provider and have that provider change for business reasons, necessitating a huge uplift.

Bear in mind that Agents and Hubs are inherently “local” to each other in an organizational sense; it’s not expected that any Agent would need to connect to a Hub operated by a wholly different organization unless some kind of contractual/outsourcing arrangement were in play, so the choice of PKI should reflect this. Most of the conventional guidance around TLS will not be based on this sort of model (even today, the commercial model suited to the WWW is constantly mis-applied internally when it should not be (e.g., databases, LDAP, etc.).

Finally, note that at present, Agents do not support client TLS authentication to hubs. While this has huge benefits, it’s incredibly hard to deploy, hard to implement at a Hub, requires a dramatically more complex PKI infrastructure, and largely depends on solutions to problems that have never been solved (they’re why SAML and its successors exist in fact).