SAMLBasics

Configuration Files

The SAML protocol plugin will add only one new file to the system:

• conf/sp/saml.properties

  • Global/default SAML options, paths to default keys and certificates

It’s simplest (and automatic) to rely on a single set of keys shared by all Agents, but more advanced configuration can be used to control the use of multiple sets of keys for different cases in a lot of different ways. The MigratingFromV3 topic’s section on the legacy SP’s credentials discuss some of the trade offs and challenges here.

Enabling SAML

There is just a single step here, at least initially; simply install the SAML protocol plugin (net.shibboleth.plugin.shibd.saml).

Doing so for the first time will generate a signing keypair and an encryption keypair that are stored in files under credentials/sp/ and are referenced in the properties file the plugin adds to the system. This initializes the system to use that set of keys and certificates for all Agents connected to the Hub by default. The content of the certificates follows similar conventions to the one used by the IdP installer, namely to include some hostname information, but in practice this doesn’t matter much.

The Hub automatically does a few things for you when detecting the presence of the SAML plugin:

• Enables all the supported SAML profiles (with default behavior) for all Agents/Applications.

• Defines the necessary SAML web flow operations on behalf of the Agent to support initiating sessions and handling all the available SAML bindings for the various profiles supported.

Eventually you can control that at a much deeper level if you need to, but usually there is no need to worry about it.

Keys and Certificates

SAML SPs typically possess keypairs for two purposes, decryption and signing. The former is more important than the latter, which is typically only needed when supporting SAML Single Logout. For completeness the SAML plugin assumes both sets of keys are available when it starts up by default, and it generates a default set of keys and certificates to use that are defined internally based on a few properties. For a new install, this is certainly enough to get started.

If you are migrating an older SP and operating the Hub solely for its use, then it’s likely you may want to reuse an existing set of keys, while a new installation or a shared Hub will typically operate using a newly generated set of keys.

The default properties in conf/sp/saml.properties assume your keys live in these files, though you can certainly adjust them if desired. (Note that the use of an sp subfolder is assumed.)

The examples below assume the use of Linux and various default paths but can be adjusted in the obvious ways. They also assume the use of unencrypted keys, matching the legacy SP and Hub defaults. Refer to TBD for instructions on using encrypted keys.

Importing Existing Legacy Keypairs

Reusing existing keys can in principle allow a new Agent/Hub pair to operate as an existing deployed SP to all outward appearances, assuming the Agent configuration is modified to accomodate the legacy endpoints.

To reuse existing keys deployed with a legacy SP, assuming they’re in PEM format, simply copy them to the appropriate (typically already in use) filenames as shown above. By default, a legacy Shibboleth SP would generate them in that format and without a password, so they will work as is.

Generating Additional Keypairs

You can when desired generate additional keypairs using the IdP’s command line tool:

The example above places an entityID value into the certificate, which is purely a documentation aid, and not required or operationally relevant. A hostname is required by the tool, though as these are never used for TLS, that is also to self-document.

Using Additional Keypairs

The above examples demonstrate one way of generating additional keypairs, but does not address how you would actually use them. That is a more complex topic and involves the use of a new service introduced by the “shibd” plugin called the Credential Resolver service. This service is a new mechanism for housing potentially more advanced ways of specifying credentials of different kinds and associating them with requests in different ways. It can range from simple use cases to very complex ones and is a more intermediate discussion.

When first starting out, sticking with a single keypair (either new or copied from an older SP) is best, and when you’re ready to tackle more advanced needs, refer to TBD for help with this.

EntityIDs and Discovery

The two critical and unavoidable settings you have to have for SAML to work are the entityID of the SP (what you’re deploying) and the IdP (who you’re connecting to). Because the Agent and Hub are both now protocol-agnostic, we tend to use generic terms for these now instead of “entityID”.

Issuer

The SP’s identity is set with an “issuer” property. You can set this globally with the sp.issuer property in conf/sp/sp.properties. If you need to get more complex and support multiple non-overlapping Agents in the Hub, you would set thep:issuer property in each Agent bean in conf/sp/agents.xml:

Note that you as Hub operator MUST curate and assign the entityIDs used by all of your Agents. A sensible convention is to use a stable, public URL for a service that’s not likely to change, and add “/sp” on the end. Note that you SHOULD NOT change an in-use production entityID, ever, barring the organization losing its domain name. For testing obviously it’s not that important but for production use, be deliberate about them.

Authenticating Authority

You will in most non-federated scenarios be able to directly establish the entityID of the IdP you want to connect an Agent to. For global default assignment as in an enterprise scenario, you can set this with the sp.defaultAuthority property in conf/sp/sp.properties. If you need to override the value for a particular Agent, you would set thep:authenticatingAuthority property in the Agent bean in conf/sp/agents.xml:

Discovery

In federated systems, it’s typically impossible to pre-define exactly which IdP should be used by an Agent. The Hub deals with this by supporting the IdP Discovery protocol defined originally by the Shibboleth Project, which works with any “typical” SSO protocol (if you are told it’s SAML-specific, you are being misinformed). There are a variety of compatible DS implementations around, including the seamlessaccess.org system.

To use a DS, you:

1. Unset the sp.defaultAuthority and/or unset the p:authenticatingAuthority bean property on any Agents requiring use of a DS. Note that if the bean property isn’t set to something (null is an option), the global property would take effect in its place.

2. Set one of these two properties:

   1. sp.discoveryURL – directly sets the URL of a DS to use

   2. sp.discoveryURLFunction – name of a bean which implements a Java/Scripted/etc. Function to return the URL of a DS to use

These properties are global; any Agent/Application without a defined p:authenticatingAuthority to use will attempt discovery if one of those properties is set. You may also set the p:discoveryService or p:discoveryServiceLookupStrategy bean properties directly on an Agent/Applpication bean for more precise behavior.

In the absence of any discovery service settings, if the Hub cannot generate a request to an acceptable authority without invoking discovery, it will report an error to the requesting Agent.

SAML Metadata

Shibboleth IdP and SP software support SAML through the exchange of SAMLMetadata, XML documents that describe systems that implement protocols such as SAML, CAS, OpenID Connect, and others. As with the standardized IdP Disovery protocol introduced by the SAML committee, SAML Metadata is not, and was never intended to be, SAML-specific.

Obtaining SP Metadata

At present, we have no automatic means of providing Metadata representing the SP to the world; it is a requirement that such Metadata be produced and supplied by “some” means to the idP(s) with which you wish to connect. We will likely by the time the Hub is officially released be providing some kind of tooling to assist with producing Metadata, but not in an online “point IdPs to it” sense.

For the time being, obtaining any example of SP Metadata and pasting in the relevant entityID, URLs, and key(s) will get you what you need:

• The entityID is what you configure in the earlier step above as the “issuer” setting.

• The certificates produced by the installer can be found at the locations specified in conf/sp/saml.properties. The encryption certificate is the more important one. The signing certificate should rarely be used apart from logout, and almost all non-Shibboleth IdPs ignore logout signatures anyway.

• The AssertionConsumerService locations come from the Agent(s) acting under the auspices of the SAML Metadata being prepared, which could involve one or many actual virtual hosts across one or many physical Agents. The default path used by Agents for the ACS is now /Shibboleth.sso/Validatefor all SAML bindings (though HTTP-POST is usually the only critical one to advertise).

  • There are advanced Agent options that support compatibility with pre-V4 binding-specific endpoint paths and in such cases you would tend to have already published Metadata anyway, as the whole point of the legacy feature is to enable compatibility with existing Metadata.

The Hub itself does not need, and will not consume, the SP Metadata and cannot “enforce” any correctness or consistency against the Hub’s configuration (in fact doing so would subvert its purpose since Metadata often differs from physical deployment details deliberately to allow advance publication of planned changes to keys or endpoints).

IdP Metadata Import

You will need to provide SAML Metadata for all IdPs the Hub is expected to interact with by configuring Metadata sources of various possible types using the Shibboleth IdP’s existing MetadataConfigurationfeatures. The IdP’s built-in Metadata Resolver service, confgured in conf/metadata-providers.xml, is automatically plumbed into all Agents for shared usage, and it is a bad idea to try to complicate this by limiting Metadata to less than global visibility to all Agents. Metadata is simply “truth”, and it is not an appropriate isolation mechanism to limit use of the information; there are far more effective techniques for that.

Managing and sourcing Metadata is a very complicated and critical task, but there’s no way to tackle the full scope of that problem out of the starting gate (and the answers are rather unpleasant and don’t include words like “simple” or “easy”). For now, the examples below will get you started.

Down the road, you can look at SAMLMetadataApproaches for a more in-depth discussion of strategies and pitfalls.

Simple Testing

Let’s assume you can acquire a SAML Metadata document for an IdP you want to test with. Place it in a file in the metadata directory in the Shibboleth IdP installation your Hub is running under. Then configure the following in conf/metadata-providers.xml (using the filename you created):

MDQ

If you expect to be operating in the context of a SAML trust federation that provides an MDQ metadata service (or even if a single IdP you need to support is published by one), it is strongly advisable to use it. This requires the use of the DynamicHTTPMetadataProviderand some built-in options, and you can get documentation on this from the various federations that operate them:

• InCommon

• Your link here…

Note that when federations offer both SP and IdP documentation for Shibboleth, it’s the IdP documentation you will need since for now the SP documentation will refer to our older software, while this version runs in the context of the IdP software’s metadata service.

Attributes

The primary function of this collection of software is to get data about a logged in user into an application. The Hub is responsible for producing the data from a potentially wide combination of sources and then packaging it in a simple form for the Agent to consume. With SAML, the primary source of that data will be the SAML Response/Assertion the Agent receives and passes up to the Hub for processing.

All data that the Hub extracts and passes to the Agent will be decoded into IdPAttribute objects with one or more values (various subtypes of IdPAttributeValue). The Agent will transform all supported types of values into strings when it receives them; the Hub maintains the fidelity of more complex types because future Agent implementations might have more advanced features for consuming the information.

Sources

There are a handful of (mostly optional) steps involved in producing this set of IdPAttributes. When getting started, you can ignore the more advanced capabilities (discussed TBD), but a summary of the sources includes:

• Automatic behavior decoding the SAML <NameID> and <Attribute> elements from the Assertion(s) validated from an IdP using the Hub’s AttributeRegistryConfiguration. This is the primary source of data and is always active.

• Optional support for decoding a set of “standard” IdPAttributes consistent with the legacy SP. See more on this below.

• Optionally invoking a custom Java or scripted Function to produce additional data either from the SAML response or other sources.

• Optionally running the Hub’s Attribute Resolver service to produce additional data from local sources, transform data, etc.

Many standard rules are installed by default, so when following standards and using common Attributes, you may not have to add many others. The default ruleset in the latest IdP software includes a couple of rules for two common <NameID> Formats (emailAddress and persistent), but you will need to add rules for additional Formats if required (copying the existing examples is a starting point, see conf/attributes/samlSubject.xml).

In the event you do need to define additional rules, a simple way to do so is to drop a property file into the conf/attributes/custom folder per TranscodingRuleConfiguration(there are SAML examples on that page).

“Standard” Attributes

The legacy SP included support for a special set of variables produced from meta-information from the SAML response. Some applications rely on this information, so it remains optionally supported, though disabled by default. A set of properties at the bottom of conf/sp/saml.properties globally enables this feature along with establishing the attribute IDs to create for Agents. The sp.saml.extractStandardAttributes property globally enables this feature, while it can be controlled on a more fine-grained basis using a profile configuration setting.

Filtering/Acceptance

Assuming you are able to decode the data successfully, an additional required step is to “accept” them via the AttributeFilterConfiguration. This enables control over which data a particular authority can supply during SSO.

The IdP’s configuration (which is used by the Hub) does not default to accepting anything for security reasons. In lieu of fully tackling the filtering layer while initially testing, you can set the property sp.saml.acceptUnfilteredAttributes in conf/sp/saml.properties to essentially bypass use of the filter and accept “anything unspecified” that is decoded and has no explicit rule defined.

An example policy is also copied to conf/examples/attribute-filter-sp.xml that demonstrates a policy for imposing some value and scope rules on common eduPerson and SAML attributes. That example can be combined with the noted property to get something that is close to the older SP’s defaults.

Further Reading

For a more complete discussion of SAML profile usage and features, refer to SAMLProfileConfigurations.