Namespace: urn:mace:shibboleth:2.0:resolver
Schema: http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd
Overview
The StorageService
DataConnector generates results from a query against the IdP's StorageService API (see also StorageConfiguration). It's main value is in prototyping certain features that require persistent storage without the need for new code, and because the IdP includes an in-memory service by default, it's easy to use for testing with no extra configuration.
The interface to storage relies on lookup of a single record at a time, but the data connector also allows scriptable response handling that can parse the content of a storage record into multiple results, if the record is in a parseable form such as JSON.
General Configuration
The connector marries three essential pieces of configuration to be supplied by the deployer:
The lookup criteria are produced by evaluation of a pair of Velocity templates supplied with the <ContextTemplate>
and <KeyTemplate>
elements.
The two supplied response processing implementations consist of:
A simple mechanism that exposes the entire record content as a single attribute (configured with the generatedAttributeID
setting to name the attribute).
A more complex approach using the <RecordMapping>
element to supply a script to produce attribute data from the record arbitrarily.
At minimum, a storageServiceRef
attribute must be supplied to provide the StorageService to use.
Context/Key Template Contexts
Several variables are available in the two template contexts. In practice, $resolutionContext.principal
and various named dependent attributes (if any) tend to be most useful.
Name | Type | Description |
---|
resolutionContext | AttributeResolutionContext | Commonly useful members include $resolutionContext.principal and $resolutionContext.attributeRecipientID |
custom | Object | Optional object injected via customObjectRef attribute |
foo, bar, etc. | List<IdPAttributeValue> | For each IdPAttribute available from all the provided dependencies, the attributes' values are available as a collection under the attribute's name. |
Examples
Any examples here omit the Spring beans that define the StorageService to use. This service may be one used for other purposes within the IdP, or may be defined specifically for this purpose.
<DataConnector id="storageConnector" xsi:type="StorageService"
storageServiceRef="shibboleth.StorageService"
generatedAttributeId="storageRecord">
<ContextTemplate>org.example</ContextTemplate>
<KeyTemplate>$resolutionContext.principal</KeyTemplate>
<ResultCache expireAfterWrite="PT5M"/>
</DataConnector>
Reference
Specific XML Attributes
The only required attribute is storageServiceRef
.
Name | Type | Default | Description |
---|
storageServiceRef | Bean ID | | Bean ID of the StorageService instance to use |
generatedAttributeID | String | | Name of attribute to populate with the entire storage record value. Mutually exclusive with the <RecordMapping> element. |
noResultIsError | Boolean | false | When true, failure to find a matching record produces a resolution exception instead of no result |
customObjectRef | Bean ID | | Injected into context and key template generation as $custom variable |
mappingStrategyRef | Bean ID | | Bean ID of a StorageMappingStrategy to process the result set in a pluggable way |
executableSearchBuilderRef | Bean ID | | Bean ID of an ExecutableSearchBuilder<StorageServiceSearch> to produce the request to execute |
templateEngine | Bean ID | | Bean ID of a org.apache.velocity.app.VelocityEngine to use for processing the URL template, generally unnecessary |
Specific XML Elements
Name | Cardinality | Description |
---|
<ContextTemplate> | 0 or 1 | Velocity template producing the storage context to query |
<KeyTemplate> | 0 or 1 | Velocity template producing the storage key to query |
<RecordMapping> | 0 or 1 | Inline or external script to execute to process the response body |
<ResultCache> | 0 or 1 | Defines how results should be cached. |
<ResultCacheBean> | Bean ID (in the element content) defining how results should be cached as an externally defined com.google.common.cache.Cache<String,Map<String,IdPAttribute>> |
Common XML Attributes
Name | Type | Default | Description |
---|
id | String |
| Identifier for the DataConnector. This is used for logging, to establish dependencies, and as a target for failover. |
activationConditionRef | Bean ID |
| Bean ID of a condition to decide whether to resolve this connector, see here. Mutually exclusive with relyingParties and resolutionPhases and variants |
relyingParties | Space-delimited list |
| List of entity IDs for which this connector should be resolved. Mutually exclusive with activationConditionRef |
excludeRelyingParties 4.1 | Space-delimited list |
| List of entity IDs for which this connector should not be resolved. Mutually exclusive with activationConditionRef |
resolutionPhases 4.1 | Space-delimited list |
| List of resolution phases (i.e. flows) during which this connector should be resolved. Mutually exclusive with activationConditionRef |
excludeResolutionPhases 4.1 | Space-delimited list |
| List of resolution phases (i.e. flows) during which this connector should not be resolved. Mutually exclusive with activationConditionRef |
exportAttributes | Space-delimited list |
| List of attributes produced by the DataConnector that should be directly exported as resolved IdPAttributes without requiring actual AttributeDefinitions. In the case of a name clash (a DataConnector exports an attribute with the same name as an AttributeDefinition, or another DataConnector exports the same attribute) the DataConnector attribute is NOT added and a warning issued. |
noRetryDelay | Duration | 0 | Time between retries of a failed DataConnector (during the interval, failure is just assumed when the connector is run and no actual connection is attempted) |
propagateResolutionExceptions | Boolean | true | Whether connector/plugin failure is fatal to the entire attribute resolution process |
Name | Type | Description |
---|
springResources | String | DEPRECATED in 4.3 A series of ';' separated resource names which contain Spring definitions for this connector. Not valid for ComputedId and Stored DataConnector. |
springResourcesRef | Bean ID | DEPRECATED in 4.3 Bean ID of a List<Resource> which contain Spring definitions for this connector. See below. Not valid for Computed and Stored DataConnector |
factoryPostProcessorsRef | Bean ID | DEPRECATED in 4.3 Bean ID of a List<BeanFactoryPostProcessor> for use when parsing the resources specified by springResources or springResourcesRef |
postProcessorsRef | Bean ID | DEPRECATED in 4.3 Bean ID of a List<BeanPostProcessor> for use when parsing the resources specified by springResources or springResourcesRef |
profileContextStrategyRef | Bean ID | DEPRECATED in 4.3 Bean ID of a function injected to override the normal lookup process for the request's ProfileRequestContext |
Common XML Elements
Name | Cardinality | Description |
---|
<InputAttributeDefinition> | 0 or more | This element identifies an attribute definition which is an input to this data connector |
<InputDataConnector> | 0 or more | This element identifies a data connector whose attributes are to be input to this data conector |
<FailoverDataConnector>
| 0 or 1 | This element has a single attribute ref="whatever" whose content is the identifier of a data connector to resolve if this data connector fails (for instance due to the external data source being unavailable) |
Spring Configuration
If the springResource
or springResourceRef
attributes are specified, then the configuration of the DataConnector bean is partially delegated to the supplied resources. The system will create a factory for a StorageServiceDataConnector object, and look for beans in the Spring resource(s) supplied that match the types of properties supported by that type and its parent classes.
The connector may be supplied with beans of the following types:
In addition native bean IDs can be injected as follows:
The StorageService instance is injected via the storageServiceRef
attribute.
The builder for the query can be specified as an externally defined bean via the executableSearchBuilderRef
attribute (as a replacement for the <ContextTemplate>
element and related elements). This allows for complete generality of the query-building process.
The processing of the response can be specified with an externally defined bean via the mappingStrategyRef
attribute (as a replacement for the <RecordMapping>
element).
The caching of results can be specified as an externally defined bean via the <ResultCacheBean>
element (as a replacement for the <ResultCache>
element).
Rarely, a non-default Velocity engine can be injected via the templateEngine
attribute.