The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
RelationalDatabaseConnector
Namespace: urn:mace:shibboleth:2.0:resolver
Schema: http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd
Overview
The RelationalDatabase
DataConnector generates multiple IdPAttribute objects from a relational database via a JDBC DataSource. The results are generated such that each IdPAttribute represents a column of the query result set. The ordered values represent the rows of the result set and each IdPAttribute will contain the same number of values, including any embedded nulls in the results. Nulls are represented explicitly with objects of type EmptyAttributeValue as placeholders within the ordered lists.
Data Sources and Drivers
This connector uses a JDBC DataSource to connect to the database. This can be supplied via a few different techniques, but the recommended approach is to define one using Spring syntax in global.xml (or similar location) and use the <BeanManagedConnection>
element, the reason being it can be easily shared across multiple connectors. If you need the ability to reload the data source's settings, then the suggested approach is to create a new Spring file to contain the bean, and add it to the set of AttributeResolverConfiguration resources in services.xml
No matter where or how you define the data source, it is your responsibility to obtain and install the JDBC driver you want to use. The IdP does not come with any drivers, to avoid them becoming stale.
Whatever driver you use should generally be installed to edit-webapp/WEB-INF/lib, after which you will need to stop your container, rebuild the warfile, and restart the container. Failure to do so will lead to ClassNotFound exceptions that reference the driver class.
Connection Pooling
If you want to use connection pooling, the Apache DBCP library is included with the IdP. The DBCP library provides various DataSource implementations that wrap an actual database driver, and you will have to add the driver itself as well. A rudimentary example is included below, but be aware that there are a lot of options available and no particular "best practice" is implied by our limited experience with them.
Read Only Connections
Previous versions of the IdP marked the connections used for attribute resolution as read-only. A configuration attribute was provided to override this behavior and allow connection pools to be shared between the RDBMS Data Connector and other read-write uses. In V4, the DataConnector no longer marks the connections as read-only itself. If you want to enforce read-only behavior, you should do so via the JDBC connection URL and/or limiting the access of the service account.
Reference
Spring Configuration
The springResource
or springResourceRef
attributes are DEPRECATED in V4.3 and will not work in V5
If the springResource
or springResourceRef
attributes are specified, then the configuration of the DataConnector bean is delegated to the supplied resources. The system will create a factory for an RDBMSDataConnector 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.
In prior versons, most of these extension points were non-API classes and interfaces, but in V4+ they have been moved and promoted to API status.
In practice, the RDBMS Data Connector may be supplied with beans of the following types:
ExecutableSearchBuilder<ExecutableStatement>
Two classes which implement this interface are available:com.google.common.cache.Cache<String,Map<String,IdPAttribute>>
The only class available in the IdP which implements this Interface is NonFailFastValidator
The only class available in the IdP which implements this Interface is StringResultMappingStrategy
In addition, native bean IDs can be injected as follows:
The DataSource can be specified as an externally defined bean via the
<BeanManagedConnection>
element (as a recommended replacement for the the<ContainerManagedConnection>
element).The builder for the SQL query can be specified as an externally defined bean via the
executableSearchBuilderRef
attribute (as a replacement for the<QueryTemplate>
element).The mapping of column names can be specified as an externally defined bean via the
mappingStrategyRef
attribute (as a replacement for the<Column>
elements).The caching of results can be specified as an externally defined bean via the
<ResultCacheBean>
element (as a replacement for the<ResultCache>
element).A Validator can be specifier as as an externally defined bean via the
validatorRef
attribute. The only available class which implements this Interface is NonFailFastValidatorRarely, a non-default Velocity engine can be injected via the
templateEngine
attribute.
Examples
Simple DataConnector entirely in custom syntax
Simple Data Connector using external bean
The example below demonstrates a number of approaches:
Use of a Spring file to define the various low-level objects, which could be referenced via
<DataConnector" xsi:type="RelationalDatabase" springResources="....." />
Use of a Spring file to define a data source which could be referenced via
<BeanManagedConnection>dataSource</BeanManagedConnection>
Use of the DBCP pooling library to wrap a database driver in a simple pool.
Example of a springResources file