This software is not yet released and this is preliminary documentaton subject to significant change. It should not be used in production or to protect important resources at this stage.
CredentialResolverService
Overview
In addition to the AgentResolverService, the Hub supplements the IdP’s supplied services with a second new service called a Credential Resolver, which addresses a long-standing IdP problem in scaling the definition and use of multiple sets of keys for various purposes and the largely “manual” process of adding new keys and certificates to the system. This is a more acute problem with the Hub for a couple of reasons:
The desire to support discretely operating Agents that may already have been deployed with their own keys dating to earlier SP versions, or to override keys for specific IdPs.
The basic model of client secrets in OpenID/OAuth, which is a non-federated, shared-secret architecture in which a large number of secrets have to be managed to support a large number of OPs.
As noted in CredentialResolverBasics, the use of this service by Hub plugins is automated during initial installation, but left to the deployer for more advanced cases. This topic speaks to those cases and how to take advantage of the service more fully when required.
The default configuration file to extend use of this service is conf/sp/credentials.xml (the exact set of resources can be adjusted, control over service reload, etc. as with other IdP services, see ServicesReference).
Notably, since this is a reloadable service (on demand or when changes are detected), the Hub can dynamically be adjusted with changes to credential information or access mechanisms, which also reloads/clears any caching done by the service. The service ID for this is shibboleth.sp.CredentialResolver.
Configuration
The only initially “visible” configuration of this service is the set of properties that govern how the service is managed and not anything to do with credentials or their use. As you install additional plugins that need their own credentials, those plugins will typically generate default sets of credentials and support new properties that reference them, extending the configuration internally to make them known to the Hub when they’re needed and on what basis.
An empty file (sp/conf/credentials.xml) is supplied for subsequent use in adding additional credentials and rules for using them to the Hub. The bulk of this topic refers to how to use this file if you need it.
Most of the time, if you add anything to that file it will be a bean (or beans) adding some kind of CredentialResolver object to the system. Sometimes these beans may contain, or reference, actual Credential beans you also need to add to the file (though usually any secret or private material would be stored separately of course). Other times, the resolver may be more abstract, such as a mechanism of auto-generating filenames to credentials on disk, or perhaps loading them from a database. The specifics will vary, and depend on the specific type of resolver and will be documented with examples in each case.
Prioritization
The only “high level” consideration to be aware of is priority. Any CredentialResolver bean you define will be of a variant that allows a relative “order” to be assigned (lower number = higher priority).
Priority affects the lookup of “ike” credentials in similar scenarios; that is, if the system requests OIDC client secrets, it doesn’t matter what the priority is relative to resolvers that return private keys and certificates. And you can often further isolate resolvers to specific protocols even when the underlying objects are alike.
But in every case, all of the configured resolvers will have a chance to examine the resolution request and respond (or not), and the order property attached to each bean will sort the resolvers in the system for you regardless of what order they may appear in the configuration.
Notably, the “internal/default” resolver(s) created internally when installing plugins typically will run last, at the lowest priority setting. This allows them to supply default credentials that will tend to be supplanted if any resolvers you configure happen to return anything.
Overriding Default Credentials
As a special case, it is possible to override or supplement the default credentials returned by the “resolvers of last resort” installed by various plugins. This is a special case that avoids the need to actually configure additional resolvers just to supply additional keys, such as when migrating between old and new keys (this is common with encryption/decryption to support multiple decryption keys at once).
SAML Defaults
For the SAML plugin, a bean named shibboleth.sp.saml.DefaultCredentials will be used in place of the internal definitions supplied with the plugin. This bean must be a list of Credential objects that must be furher identified as either signing or encryption keys as per the example below.
In fact, this example actually demonstrates a bean that is functionally identical to the internal default used in its absence, relying on the pre-defined properties noted elsewhere to identify the files used.
Following from this example, you can easily add a second globally usable decryption key by adding an additional bean to the list. Just make sure the usageType is set appropriately.
Supported Resolvers
(work in progress)
Default Credentials | The default resolver can define credentials “globally” for particular protocols or use cases, but will be resolvable for use by any Agent/Application for any RelyingParty. Does not support “fine grained” selection other than by type, protocol, and usage. Mentioned for completeness, but you will never need to use this type explicitly, as it is simpler to override the list of credentials served by the existing static resolver defined inside the system, as above under Overriding Default Credentials. |
This alternative resolver allows credentials to be defined in nested maps in Spring XML to allow the specification of credentials for particular Agents and Relying Parties (and optionally even Applications). Also allows rules to be defined that apply to all Agents and/or Relying Parties. This is designed to help with a couple of common cases:
It does not work especially well when those cases are combined as things will multiply out of hand very easily. For larger use cases, the storage-based resolvers noted below are generally more suitable. | |
StorageService-Based Resolvers
| These resolvers are the main way to “automate” fetching of credentials from the file system or a database using a set of conventions you supply to the resolver to allow it to figure out how to query for credentials in specific cases. By design, they are happy to “fail” to locate anything at a particular location if intended only for a few “exceptions” to the use of the default credentials. But they can also be configured to operate as a more fundamental source, by for example looking for each Agent’s credentials in a folder containing files with particular naming conventions. With some simple scripting (outside the Hub) to install keys and certificates (or client secrets) to those locations, you can create a very simple configuration that automates lookup for hundreds of Agents and/or scenarios. For specifics and examples, refer to the various subtypes of resolver noted on the left, which are differentiated by what type of data format(s) they load “from” and what type of Credential they produce. Note that the specific StorageService you supply will dictate where the resolver goes looking for information, but the configuration of the resolver is largely independent of that decision. You can easily mix and match using the file system to locate keys and certificates while using a database for client secrets, etc. |