GettingStarted

This is the place to start if you’re deploying the Shibboleth SP Hub for the first time. The set of topics below covers the basics of what you have to configure and how to use the Hub to do something useful. They are not an exhaustive reference of all the software features and options and they focus on the choices you have to make to get things operational in support of one or more Agents.

Most of these steps apply regardless of

If you’re upgrading from V3, also refer to the MigratingFromV3 topic. It’s best ignored if you’re starting from scratch.

1 Configuration Files
2 Basic Agent Definition and Connectivity
3 Next Steps

Configuration Files

Each SP Hub plugin will install a small number of additional configuration files into the IdP installation, predominantly under sp subdirectories added in various places (e.g., conf/sp, views/sp, and so on). The “core/base” plugin installs only these files:

conf/sp/sp.properties
- Global/default behavior and to more easily configure a single-Agent/local-Hub deployment on the same host
conf/sp/agents.xml
- “Full” configuration of Agents, Applications, and Relying Party/Profile behavioral settings
conf/sp/credentials.xml
- Initially empty, this is used as directed by protocol plugins as a place to configure more advanced key and certificate handling or access to other secrets. With a single Agent this is rarely necessary but becomes more interesting or necessary when multiple Agents are supported or for OIDC’s client secrets, which have to be managed per-OP

Typically you will establish the baseline settings and global defaults in sp.properties, and use agents.xml for ongoing maintenance of the Hub and adding additional Agents (if applicable).

Eventually, some of the IdP’s existing configuration files will become important to modify for various purposes, but other topics will cover this when necessary, or simply refer to that documentation.

Basic Agent Definition and Connectivity

Your first need will be to get Agent(s) defined and connected to your hub.

Emulating older versions' use of “shibd” as a local daemon is covered in the next sub-section, while a more scaled out/shared approach is covered in the sub-sections following. In the most advanced cases, you will eventually want to take a look at HubPlanning.

Local Hub, Single Agent

A single Agent running on the same host is supported immediately after installation, assuming the Hub is operating over plain HTTP on port 8080 (which is a common default for Jetty and other Java web servers). Both the Agent and the Hub’s configuration default to supporting an Agent called “localhost” with no authentication secret and connection limited to the IP4/6 loopback addresses.

If you want or need to do something just “slightly different” such as running the Agent and Hub over a local Docker network, this may still be sufficient except for setting the sp.authn.allowedAddressRanges property (conf/sp/sp.properties) to the address range of the Agent’s internal connections. This should only be done if the traffic remains confined to the host; otherwise, you will need to migrate to a protected and secured connection (essentially a simple case of the approach outlined in the next section).

Networked Hub, Single Agent

Adding networking requires the addition of a shared secret to authenticate the Agent, and shifting to a TLS-enabled hub. The secret can be handled many different ways, but for testing you can start very simply by setting the sp.agent.authn.method property (conf/sp/sp.properties) to “basic” and adding a hardcoded secret to the hub’s configuration and sharing it with the Agent operator. The secret can be added as a bean property in conf/sp/agents.xml:

...
<bean p:id="localhost" parent="shibboleth.sp.Agent" p:credentials="#{ {null : 'abcdefg'} }">
...

The credentials property is a Java Map of username/password pairs to internally support in lieu of an externalized approach to managing service accounts for Agents to use. Obviously you can make the secret as long and random as you wish. The default Agent ID (i.e., the username) of “localhost” can remain the same unless desired (which would require a similar change to the Agent). In the example above, the null expression is a signal to use the bean ID (“localhost”) as the username.

The Agent deployer must supply that secret to the Agent in a file or via environment variable (see ConnectingToHub).

Running the Hub with TLS-enabled is a Java servlet container matter; however, the choice of server certificate will impact your Agent as it must configure either that certificate directly or one of its chain of issuers as a trust anchor. If the container is operating solely as a Hub (i.e., not as an IdP as well), then a self-signed key or locally managed PKI are good options, particularly for testing. We expect that to be the most common scenario.

Finally, the sp.agent.authn.allowedAddressRanges property (conf/sp/sp.properties) must be unset, or set to an appropriate address range, as the default ranges allow only loopback connections.

Networked Hub, Multiple Agents

This is the most general case, as a Hub can serve (within reason) any number of Agents, operating jointly across a clustered web site or independently for different web sites.

In this scenario, the Hub must obviously be TLS-enabled and the wider the pool of Agents, the more well-thought out the PKI aspect needs to be, since updating a trust anchor across many Agents is obviously laborious and disruptive. As above, if operating solely as a Hub and not as an IdP more generally, a locally managed PKI is a good option here.

The chief complication in this scenario is the need to plan for credentialing the Agents. The usual model is to consider all Agents acting “together” for a clustered application as a unit and give them a common Agent ID and secret, just as more traditional clustered SAML SP Agents would tend to share a keypair. Most examples will assume this approach. Agents operating “separately” would be expected to possess different Agent IDs and secrets. The obvious analogy would be a service account issued to a clustered application for access to a common database.

The main thing to understand at this stage is that you will have to define a bean for each “collection” of linked Agents that should be identified together. These may all be defined in conf/sp/agents.xml, or you may use multiple files imported into that one in the usual Spring fashion (e.g., to develop a more scripted/automated approach to adding them).

Initially, don’t worry about getting fancy; just define an Agent bean. In this example, some specific network ranges are applied to each Agent to further secure the system, and we demonstrate a mix of Spring XML and use of properties for defining settings that are specific to, or common to, each Agent respectively. That is, properties are global defaults while beans can override settings where needed.

It is assumed that Agent secrets will be validated “somehow”; see SecuringAgentConnections for a quick start guide to Agent secret validation. Most of the time that will be defined separately for all Agents collectively and won’t require any per-Agent configuration to set up. In the example below, both “internal” validation of requests and “external” use of service accounts managed separately are shown for illustration’s sake. In reality of course you would choose an approach to use.

conf/sp/sp.properties

...
# Use of a single IdP for all agents
sp.defaultAuthority = https://idp.example.org
...
# Override the default authentication type
sp.agent.authn.method = basic
...

conf/sp/agents.xml

...
    <!-- Example of "internal" secret validation with the username left as the bean ID. -->
    <bean p:id="app1.example.org" parent="shibboleth.sp.Agent"
        p:allowedAddressRanges="192.168.1.0/24"
        p:credentials="#{ {null : 'abcdefg'} }"
        p:issuer="https://app1.example.org/sp" />

    <!-- Example of "external" secret validation using a pair of service account usernames. -->
    <bean p:id="app2.example.org" parent="shibboleth.sp.Agent"
        p:allowedAddressRanges="192.168.2.0/24"
        p:usernames="#{{ 'SA1-spagent-app2', 'SA2-spagent-app2' }}"
        p:issuer="https://app2.example.org/sp" />
...

This obviously generalizes to any number of Agents, and there are a large number of additional options, but for a single-IdP deployment, this gets you fairly far.

The issuer bean properties there associate each Agent (or cluster of Agents) with a particular protocol identity (SAML entityID or OpenID client_id). Because multiple different values are assumed in the example, a global property won’t work, but we do use a property to define a single IdP/OP to use across both.

Note that the issuer property is not known or relevant to the Agent(s) and is controlled via the Hub. Even changing it will not impact Agent configuration, nor is there any implied relationship between it and the Agent’s bean ID, though conventionally one might assume some imposed relationship for obvious reasons.

If locking down the address ranges is impossible or undesired, you can simply define the sp.agent.authn.allowedAddressRanges property globally to the largest ranges you can get away with for all your Agents. The address checking is intended as an optional hardening feature, but the secret validation is the primary security mechanism.

Next Steps

The next steps will depend on which SSO protocol(s) you need the Hub to broker for your Agents. Typically the Agent doesn’t, and shouldn’t, know or care about this other than the question of what identity sources they expect you to support, dictating what protocol(s) you have to support to accomodate them.

For basic setup, refer to: