Page tree

Previous Stable Release

Please note that the V3 release branch is now the previous stable release, with the current stable releases from the V4 branch.
Support for V3 will end on Dec 31, 2020.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 40 Next »

The RelationalDatabase data connector generates multiple attributes from a relational database via a JDBC DataSource. The attributes are generated such that each attribute represents a column of the query result set. The ordered values represent the rows of the result set and each attribute will contain the same number of values, including any embedded nulls in the results. Nulls are represented explicitly with objects of type EmptyAttributeValue (note, this is a change from V2, which exposed null values as Java nulls in the attribute value collections).

Schema Name and Location

This xsi:type is defined by the urn:mace:shibboleth:2.0:resolver schema 3.3, located at http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd.

Prior to V3.3 supplied plugins were defined by a schema type (xsi:type) in the urn:mace:shibboleth:2.0:resolver:dc namespace, the schema for which is located at http://shibboleth.net/schema/idp/shibboleth-attribute-resolver-dc.xsd. This is still supported, but every element or type in the  urn:mace:shibboleth:2.0:resolver:dc namespace has an equivalently named (but not necessarily identical) version in the urn:mace:shibboleth:2.0:resolver namespace. The use of the urn:mace:shibboleth:2.0:resolver namespace also allows a relaxation of the ordering requirements of child elements to reduce strictness.

Examples

Simple DataConnector entirely in custom syntax
 <DataConnector id="myDatabase" xsi:type="RelationalDatabase">
   <FailoverDataConnector ref="BackupDataseConnector"/>
   <ApplicationManagedConnection 
       jdbcDriver="org.hsqldb.jdbc.JDBCDriver" jdbcURL="jdbc:hsqldb:mem:RDBMSDataConnectorStore"
       jdbcUserName="SA" jdbcPassword="secret" />
   <QueryTemplate>
       <![CDATA[
         SELECT * FROM people WHERE userid='$resolutionContext.principal'
       ]]>
   </QueryTemplate>
 
   <Column columnName="homephone" attributeID="phonenumber" />
       
   <ResultCache elementTimeToLive="PT10S"/>
</DataConnector>
Simple Data Connector using external beans
<DataConnector id="myDatabase" xsi:type="RelationalDatabase" mappingStrategy="MappingBeanId">
  <BeanManagedConnection>DataConnectorBeanId</BeanManagedConnection>
   <QueryTemplate>
       <![CDATA[
         SELECT * FROM people WHERE userid='$resolutionContext.principal'
       ]]>
   </QueryTemplate>
  <ResultCacheBean>ResultCacheBeanId</ResultCacheBean>
</DataConnector>
Example of a springResources file
<!-- In this case the definition would be <DataConnector" xsi:type="RelationalDatabase" springResources="....." /> -->

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:p="http://www.springframework.org/schema/p"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">
    <bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource" destroy-method="close" p:driverClass="org.hsqldb.jdbc.JDBCDriver"
        p:jdbcUrl="jdbc:hsqldb:mem:RDBMSDataConnectorStore" p:user="SA" p:password="secret" p:acquireIncrement="3"
        p:acquireRetryAttempts="24" p:acquireRetryDelay="5000" p:breakAfterAcquireFailure="true" p:minPoolSize="1"
        p:maxPoolSize="5" p:maxIdleTime="300" p:idleConnectionTestPeriod="360" />
    <bean id="cacheBuilder" class="com.google.common.cache.CacheBuilder" factory-method="from">
        <constructor-arg value="expireAfterAccess=10s,maximumSize=25" />
    </bean>
    <bean id="cache" class="com.google.common.cache.Cache" factory-bean="cacheBuilder" factory-method="build" />
    <bean class="net.shibboleth.idp.attribute.resolver.dc.rdbms.impl.FormatExecutableStatementBuilder">
        <constructor-arg index="0" value="SELECT * FROM people WHERE userid='%s'" />
    </bean>
    <bean id="mappings" class="net.shibboleth.idp.attribute.resolver.dc.rdbms.impl.StringResultMappingStrategy"
        p:noResultAnError="true" p:multipleResultsAnError="true">
        <property name="resultRenamingMap">
            <map>
                <entry key="homephone" value="phonenumber" />
            </map>
        </property>
    </bean> 
</beans>

Attributes

Any of the common attributes can be specified. In addition the following attributes may be specified:

NameTypeDefaultDescription

noResultIsError

booleanfalseControls whether an empty result set is an error

mappingStrategyRef

Bean ID
Bean ID of a MappingStrategy<java.sql.ResultSet> to process the result set in a pluggable way
validatorRef 3.2Bean ID
Bean ID of a Validator to control what constitutes an initialization failure (set this to "shibboleth.NonFailFastValidator" to bypass connection attempt at config load time)

multipleResultsIsError

booleanfalseControls whether a result set with more than one row is an error

queryTimeout

XML Duration or number of milliseconds
Timeout for the queries made against the database

templateEngine

Bean ID
Bean ID of a org.apache.velocity.app.VelocityEngine to use for processing the SQL template
readOnlyConnectionbooleantrueWhether the DataConnector should be marked as readonly. If the DataConnector is shared with a subsystem which requires write access (via a <BeanManagedConnection>) this must bet set to false.

Child Elements

Any of the common child elements can be specified. In addition, the following may be specified.


NameCardinalityDescription

<ContainerManagedConnection>


Exactly 1

Not permitted if the
springResource
attribute is used

Connects to a database via a JNDI DataSource defined in the container

<ApplicationManagedConnection>

Connects to a database via a JDBC DataSource defined explicitly

<BeanManagedConnection>

Connects to a database via an externally specified javax.sql.DataSource

<QueryTemplate>

0 or 1The template of the SQL query to send to the database

<Column>

0 or moreA series of remapping definitions which map a column name to an IdPAttribute ID

<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>> 

Externally (Spring) Defined Content

If the springResource or springResourceRef attributes are specified, then the configuration is delegated to the supplied resource(s).

If the springResource or springResourceRef attributes are specified, then the configuration of the data connector bean is delegated to the supplied resources. The way this works is that 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. Note that since these are not public, but implementation classes, they are subject to change, which creates some risk during non-patch upgrades, so you must take additional precautions to use this feature.

In practice, the RDBMS Data Connector may be supplied with beans of the following types:

In addition native bean IDs can be injected as follows:

  1. The data source can be specified as an externally defined bean via the <BeanManagedConnection> element (as a recommended replacement for either the <ContainerManagedConnection> or <ApplicationManagedConnection> elements).
  2. The mapping of column names can be specified as an externally defined bean via the mappingStrategyRef attribute (as a replacement for the <Column> elements).
  3. The caching of results can be specified as an externally defined bean via the <ResultCacheBean> element (as a replacement for the <ResultCache> element).
  4. Rarely, a non-default Velocity engine can be injected via the templateEngine attribute.
  • No labels