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 29 Current »

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

 Specific XML Attributes

Name

Type

Default

Description

noResultIsError

boolean

false

Controls whether an empty result set is an error

failFastInitialize

boolean

false

Whether a failure when verifying the database's availability during startup is fatal (stops the Attribute Resolver service from starting)

queryTimeout

Duration

Timeout for the queries made against the database

multipleResultsIsError

boolean

false

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

mappingStrategyRef

Bean ID

Bean ID of a MappingStrategy<java.sql.ResultSet> to process the result set in a pluggable way

validatorRef

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

executableSearchBuilderRef

Bean ID

Bean ID of an ExecutableSearchBuilder<ExecutableStatement> to produce the SQL query to execute

templateEngine

Bean ID

Bean ID of a org.apache.velocity.app.VelocityEngine to use for processing the SQL template

 Specific XML Elements

Name

Cardinality

Description

<ContainerManagedConnection>

Exactly 1

Not permitted if the springResource attribute is used

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

<SimpleManagedConnection>

Connects to a database via a JDBC DataSource defined explicitly with a simplified syntax.

<BeanManagedConnection>

Connects to a database via an externally specified DataSource

<QueryTemplate>

0 or 1

The template of the SQL query to send to the database

<Column>

0 or more

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

 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

The following table contains advanced settings rarely used in common practice.

Name

Type

Description

springResources

String

A series of ';' separated resource names which contain Spring definitions for this connector.

Not valid for ComputedId and Stored DataConnector and DEPRECATED for use with Scripted DataConnector

springResourcesRef

Bean ID

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

Bean ID of a List<BeanFactoryPostProcessor> for use when parsing the resources specified by springResources or springResourcesRef

postProcessorsRef

Bean ID

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

In addition, native bean IDs can be injected as follows:

  1. The DataSource can be specified as an externally defined bean via the <BeanManagedConnection> element (as a recommended replacement for the the <ContainerManagedConnection> element).

  2. 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).

  3. The mapping of column names can be specified as an externally defined bean via the mappingStrategyRef attribute (as a replacement for the <Column> elements).

  4. The caching of results can be specified as an externally defined bean via the <ResultCacheBean> element (as a replacement for the <ResultCache> element).

  5. Rarely, a non-default Velocity engine can be injected via the templateEngine attribute.

Examples

Simple DataConnector entirely in custom syntax
 Click here to expand...
 <DataConnector id="myDatabase" xsi:type="RelationalDatabase">
   <FailoverDataConnector ref="BackupDataseConnector"/>
   <SimpleManagedConnection 
       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" />
</DataConnector>
Simple Data Connector using external bean
 Click here to expand...
<DataConnector id="myDatabase" xsi:type="RelationalDatabase" mappingStrategyRef="MappingBeanId">
  <BeanManagedConnection>DataConnectorBeanId</BeanManagedConnection>
   <QueryTemplate>
       <![CDATA[
         SELECT * FROM people WHERE userid='$resolutionContext.principal'
       ]]>
   </QueryTemplate>
  <ResultCacheBean>ResultCacheBeanId</ResultCacheBean>
</DataConnector>

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
 Click here to expand...
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:p="http://www.springframework.org/schema/p"
    xmlns:c="http://www.springframework.org/schema/c"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">

	<bean class="net.shibboleth.idp.attribute.resolver.dc.rdbms.FormatExecutableStatementBuilder">
		<constructor-arg index="0" value="SELECT * FROM people WHERE userid='%s'" />
	</bean>

	<bean id="mappings" class="net.shibboleth.idp.attribute.resolver.dc.rdbms.StringResultMappingStrategy"
	        p:noResultAnError="true" p:multipleResultsAnError="true">
        <property name="resultRenamingMap">
            <map>
                <entry key="homephone" value="phonenumber" />
            </map>
        </property>
	</bean>

	<!-- The rest of these beans would be unneeded for a simple BeanManagedConnection. -->

	<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close"
		p:driverClass="org.mariadb.jdbc.Driver"
        p:jdbcUrl="jdbc:mysql://mysql.example.org:3306/shibboleth"
		p:user="admin" p:password="secret"
        p:maxTotal="20"
        p:maxIdle="5"
        p:maxWaitMillis="2000"
        p:testOnBorrow="true"
        p:validationQuery="select 1"
        p:validationQueryTimeout="5" />

	<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" />
</beans>

  • No labels