ConnectingToHub

A complete reference for these settings can be found in RemotingSettings.

The Agent is a comparatively small amount of code that is kept small by leveraging a much more complex system called a “Hub”, which is implemented in Java as a set of plugins to the Shibboleth Identity Provider software. The Hub is similar to, though not an exact match for, the work done by the “shibd” daemon in older SP releases.

Operating an Agent does not require any knowledge of the Hub whatsoever, by design. The only requirement for an Agent is to have a Hub to connect to because most of the heavy lifting is done by it.

It is certainly possible to run a Hub on the same host as an Agent and for the same person or persons to do both. In fact, the defaults match that, since anything else requires some non-default settings, and to simplify that case as much as possible.

In most other cases, the operators of a Hub will establish their own internal processes and provide documentation for registering with and connecting to that Hub.

The Agent will communicate to its Hub during specific operations it performs using a messaging protocol implemented on top of HTTP. The details of this protocol are of importance only to Agent implementers, not to deployers. The HTTP implementation is defaulted based on the platform.

Agents authenticate to a non-local (networked) Hub using HTTP Basic Authentication, typically over TLS.

If TLS is used, then the Hub is verified by the Agent by means of TLS certificate evaluation. This is a critical step for the Agent to take because it is the only basis by which the Agent can operate safely across a network, so there are no options (and never will be) to disable that checking aside from use of HTTP alone. Nobody can stop you from deploying an Agent unsafely, but you have absolutely no security if you do.

Connection Details

An Agent connecting to a Hub on the same host via plain HTTP works out of the box with the default settings of both the Agent and Hub (see also below). Anything else requires some simple alterations.

The information needed to allow an Agent to connect to a remote Hub consists of:

a unique Agent ID (issued by Hub or the Hub’s organization, this is the username half of the service account used by the Agent)
an Agent secret, the password to the service account the Agent will use
the base URL at which to reach the Hub (all the necessary operational URLs will be constructed automatically from this and it typically will end in “/idp/profile/sp”)
the trusted certificate(s) to use to verify the hub’s TLS certificate

All of these will be expressed as settings in the agent.ini file in the [remoting] section. Typically a Hub operator should supply its Agents with this information in the form of a file to base their configuration on, with the exception of the service account information

Localhost Use

In a scenario where the work of operating a Hub falls on the Agent deployer, a single Hub can be deployed to support a single Agent on the same host (likely listening on only the localhost loopback port on port 8080 since port 80 is privileged on Linux). This is very similar to the way the “shibd” process operated before. In such a case, use of plain HTTP without TLS is the simplest way to deploy the Hub with the best performance. The Agent ID is largely an academic exercise in such cases, and is arbitrary, the default on both sides being “localhost” as a reasonable way to express what’s happening.

Of course, TLS remains an option and a self-signed certificate can be used for the Hub and as the trust root in the Agent if desired (see RemotingSettings).

An HTTP configuration looks like this, using default settings in agent.ini:

[remoting]
agentID = localhost
baseURL = http://127.0.0.1:8080/idp/profile/sp/
#authMethod = none

These are all defaults, but the INI file parser will demand that at least one property exist under each section, so a couple of them are left uncommented for that reason. These will match the Hub’s own defaults after installation and basic setup is done, specifically the default agentID it expects to receive requests from.

Shared Use

In a scenario where a Hub is operated independently and shared by multiple Agents, the settings will depend more on decisions made by the Hub operator. The agentID setting will have to be provided by the Hub operator or organization as part of the service account issued for the Agent’s use. It obviously cannot overlap with any distinct Agents the Hub may be supporting, but a cluster of Agents can certainly share one.

TLS will almost certainly be used and so the baseURL will begin with “https://” and the tlsCAFile setting will have to point to a file containing one or more PEM-format certificates. Usually this will contain one of the CAs used in the chain of issuance, but it can be an intermediate rather than a root, which limits the scope of trust to a more granular degree than a root CA would. The ultimate goal is to balance the amount of trust exposure against the need to change the certificate, which are competing objectives.

Such a configuration for an Agent deployed with an HR service might look like:

[remoting]
agentID = SA-shib-hr.example.org
baseURL = https://ssohub.example.org/idp/profile/sp/
authMethod = basic
#authCachingCookie = __Host-JSESSIONID
tlsCAFile = trustlist.pem
#secretSourceType = File
secretFile = agent.pwd

Of course a shared Hub will also need to provide the Agent with its secret (directly or otherwise; some kind of enterprise solution to issue credentials to services is both supported and encouraged).

Managing Agent Credentials

Out of a desire for simplicity, there are no hooks for automatically rotating an Agent’s credentials. In practical terms, it’s best to get out of the archaic mindset that long random secrets ought to change constantly unless constant unplanned outages are your goal.

In the meantime, the Hub allows an Agent to be configured (on its end) with an arbitrary number of service identities with which the Agent may authenticate itself, so multiple service credentials can be issued to Agents to allow for rotation. The agentID setting in the agent.ini file is the agent’s “username” when connecting to the Hub and the Hub may internally identify the Agent in a more formal way for logging and so forth if the username(s) used are sufficiently opaque/ugly/etc.

In many of the examples shown, we demonstrate relatively “friendly” and semantically relevant agentID values, but the only real requirement is uniqueness within the Hub so requirements will vary.