Page tree
Skip to end of metadata
Go to start of metadata

Namespace: urn:mace:shibboleth:2.0:resolver
Schema: http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd

Overview

The LDAPDirectory data connector generates one or more attributes based on a query to an LDAP directory.

The underlying library used for this is called ldaptive, and many of the more advanced options are usable only by referring to its documentation, but most deployers should be able to make to do with the information we supply.

General Configuration

The IdP ships with an example configuration file, attribute-resolver-ldap.xml, that demonstrates property-driven attribute resolution, using the properties defined in ldap.properties, much of which can be shared with the LDAP Authentication Configuration for the common case of a single LDAP directory used for both authentication and attributes. You can freely mix use of properties with explicit settings.

If execution of the query returns multiple results, these are merged by default.

The following properties are demonstrated. They take their defaults from the values of the similarly-named authentication properties, but can be explicitly set to split them off as needed.

PropertyTypeDefault Authn PropertyFunction

idp.attribute.resolver.LDAP.ldapURL

URL

idp.authn.LDAP.ldapURL

Connection URL for the LDAP directory

idp.attribute.resolver.LDAP.baseDN

String

idp.authn.LDAP.baseDN

Base DN to search against,

idp.attribute.resolver.LDAP.bindDN

String

idp.authn.LDAP.bindDN

DN to bind as before performing the search

idp.attribute.resolver.LDAP.bindDNCredential

String

idp.authn.LDAP.bindDNCredential

Password to bind with before performing the search

idp.attribute.resolver.LDAP.useStartTLS

Boolean

idp.authn.LDAP.useStartTLS (defaults true)

Whether StartTLS should be used immediately after connecting to the LDAP

idp.attribute.resolver.LDAP.trustCertificates

Resource

idp.authn.LDAP.trustCertificates

A resource to load trust anchors from, usually a local file in %{idp.home}/credentials
idp.attribute.resolver.LDAP.connectTimeoutDurationidp.authn.LDAP.connectTimeout (defaults PT3S)Connection timeout in milliseconds
idp.attribute.resolver.LDAP.responseTimeoutDurationidp.authn.LDAP.responseTimeout (defaults PT3S)Time to wait for response

TLS Validation Configuration

Assuming either LDAP-over-TLS (ldaps) or StartTLS are used, you MUST configure the rules for validating the LDAP server's TLS key within the connector.

There are generally two ways to do this:

  • Reference a CA (Certificate Authority) that has signed the certificate chain presented by the LDAP server.
  • Reference the LDAP server's certificate explicitly.

The latter provides better security but likely will require constant updating and coordination with the LDAP server's operational staff unless it relies on a longer-lived certificate.

You may configure multiple certificates by concatenating PEM formatted certificates together.

You reference the certificate(s) you choose to trust by setting the trustFile XML attribute inside the <DataConnector> element, and the example below passes that through to a property you can configure separately, but that's purely a matter of style.

Note that this is distinct from configuring the IdP to authenticate itself to the LDAP server with a certificate. That relies on a different set of options (authKeyauthCert).

Examples

Simple DataConnector entirely in custom syntax
<DataConnector id="myLDAP" xsi:type="LDAPDirectory"
    ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}" 
    baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
    principal="%{idp.attribute.resolver.LDAP.bindDN}"
    principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
	trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"
	useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
    noResultIsError="%{idp.attribute.resolver.LDAP.noResultsIsError:false}"
    multipleResultsIsError="%{idp.attribute.resolver.LDAP.multipleResultsIsError:true}">
    <FilterTemplate>
        <![CDATA[
            %{idp.attribute.resolver.LDAP.searchFilter}
        ]]>
    </FilterTemplate>
    <StartTLSAuthenticationCredential xsi:type="security:X509Filesystem" xmlns:security="urn:mace:shibboleth:2.0:security" id="IdPtoLDAPCredential">
        <security:PrivateKey>%{idp.attribute.resolver.LDAP.authenticationKey}</security:PrivateKey>
        <security:Certificate>%{idp.attribute.resolver.LDAP.authenticationCertificate}</security:Certificate>
    </StartTLSAuthenticationCredential>
    <ConnectionPool
        minPoolSize="%{idp.pool.LDAP.minSize}"
        maxPoolSize="%{idp.pool.LDAP.maxSize}"
        blockWaitTime="%{idp.pool.LDAP.blockWaitTime}"
        expirationTime="%{idp.pool.LDAP.expirationTime}"
        validatePeriodically="%{idp.pool.LDAP.validatePeriodically}"
        validateTimerPeriod="%{idp.pool.LDAP.validatePeriod}"
        validateDN="%{idp.pool.LDAP.validateDN}"
        validateFilter="%{idp.pool.LDAP.validateFilter}"/>
    <ResultCache
        elementTimeToLive="%{idp.cache.LDAP.timeToLive}"
        maximumCachedElements="%{idp.cache.LDAP.cacheSize}"/>
</DataConnector>

Reference


NameTypeDefaultDescription

ldapURL

Space-delimited list of URLs

URL(s) to the LDAP server. Each listed URL is tried according to the connectionStrategy.

baseDN

String
Base DN from which the LDAP search will be executed

principal

String
Username (service DN) that the connector will use to bind to the LDAP directory

principalCredential 

String

Password used to authenticate as the principal (service DN)

lowercaseAttributeNames

BooleanfalseWhether all attribute IDs from the LDAP should be lower-cased. This can be important since Shibboleth attribute IDs are case-sensitive while LDAP attribute IDs are not.

trustFile

File pathname
Path to a file containing the X.509 trust information to use when connecting to the directory over LDAPS or startTLS. Replaces the deprecated use of <StartTLSTrustCredential>

failFastInitialize

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

connectTimeout

DurationPT3STime to wait for a connection to be established

responseTimeout

DurationPT3STime to wait for a response before failing

searchTimeLimit

DurationPT3SLength of time that a search operation should execute; a value of 0 means execute indefinitely; when time limit arrives the result will contain any entires returned up to that point

maxResultSize

Integer1Maximum number of entries to include in the search result; a value of 0 means includes all entries

noResultIsError

BooleanfalseWhether an empty result set is an error

multipleResultsIsError

BooleanfalseWhether a result set with more than one result is an error

connectionStrategy

One of ROUND_ROBIN, RANDOM, ACTIVE_PASSIVEACTIVE_PASSIVE

If Multiple URLs were provided as the ldapURL this describes how each URL will be processed.

  • ACTIVE_PASSIVE (default value) - Indicates that the first LDAP URL will be used for every request unless it fails and then the next LDAP URL will be used.
  • ROUND_ROBIN - Indicates that for each new connection the next LDAP url in the list (circling back to the start of the list when the end is reached) will be used
  • RANDOM - Indicates that for each new connection a random LDAP url will be selected

searchScope

One of SUBTREE, ONELEVEL, OBJECTSUBTREE

The scope of the search.

  • SUBTREE: The entire LDAP directory subtree below the search baseDN will be searched.
  • ONELEVEL: Only the immediate children of LDAP object corresponding to the search baseDN will be searched.
  • OBJECT: Only the LDAP object itself is searched.

derefAliases

One of NEVER, SEARCHING, FINDING, ALWAYSNEVER

How aliases should be dereferenced. See the Oracle JNDI docs for more details on these options.

followReferrals 4.0.1BooleanfalseWhether to follow search referrals and references when they are encountered in search results.

useStartTLS

BooleanfalseWhether to use startTLS when connecting to the LDAP
disableHostnameVerificationBooleanfalseWhether to enforce certificate name checking during TLS, only change if you understand the implications

authCert

File pathname
Path to the file containing the X.509 certificate to provide when connecting to the directory over LDAPS or startTLS

authKey

File pathname
Path to the file containing the private key to provide when connecting to the directory over LDAPS or startTLS

authKeyPassword

String
Password to use for the private key file

templateEngine

Bean ID
The ID of a Spring bean defining a org.apache.velocity.app.VelocityEngine

mappingStrategyRef

Bean ID
The ID of a Spring bean defining a Mapping Strategy (which converts the result of an LDAP search into a list of IdP Attributes).

executableSearchBuilderRef

Bean ID
The ID of a Spring bean defining an ExecutableSearchBuilder<ExecutableSearchFilter>

validatorRef

Bean ID
Bean ID of a Validator to control what constitutes an initialization failure if failFastInitialize is not sufficient
NameCardinalityDescription

<FilterTemplate>

0 or 1The template of the search filter to be sent to the LDAP directory server

<ReturnAttributes>

0 or 1A list of attributes to be returned from the LDAP directory server; this may help the server respond more quickly
<BinaryAttributes>
0 or 1A list of attributes whose values contain binary data and must be base64 encoded; format is a space-delimited list of attribute names, which MUST match the directory source exactly (including case and any LDAP options)

<StartTLSTrustCredential>

0 or 1X.509 trust information to use when connecting to the directory over LDAPS or startTLS, DEPRECATED in favor of the trustFile attribute

<StartTLSAuthenticationCredential>

0 or 1X.509 client authentication information to provide when connecting to the directory over LDAPS or startTLS, DEPRECATED in favor of the authCert, authKey, and authKeyPassword attributes

<ConnectionPool>

0 or 1Describes how the LDAP connection may be pooled
<SASLConfig> 4.0.10 or 1SASL configuration to provide when binding to the directory.

<Column>

0 or moreAllows for remapping of LDAP Attributes into alternately named IdPAttributes within the resolver

<ResultCache>


0 or 1

The definition of how results should be cached

<ResultCacheBean>

The definition of how results should be cached as an externally defined com.google.common.cache.Cache<String,Map<String,IdPAttribute>>,
the Spring bean ID of which is supplied as the content of the element

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.1Space-delimited list
List of entity IDs for which this connector should not be resolved.
Mutually exclusive with activationConditionRef
resolutionPhases 4.1space-delimited list
List of resolution phases (i.e. flows) during which this connector should be resolved.
Mutually exclusive with activationConditionRef
excludeResolutionPhases 4.1space-delimited list
List of resolution phases (i.e. flows) during which this connector should not be resolved.
Mutually exclusive with activationConditionRef
exportAttributesspace-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

Duration0Time 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

BooleantrueWhether connector/plugin failure is fatal to the entire attribute resolution process

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

Name

Type

Default

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
Bean ID of a function injected to override the normal lookup process for the request's ProfileRequestContext

NameCardinalityDescription

<InputAttributeDefinition>

0 or moreThis element identifies an attribute definition which is an input to this data connector

<InputDataConnector>

0 or moreThis element identifies a data connector whose attributes are to be input to this data conector

<FailoverDataConnector>   

0 or 1This 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 LDAPDataConnector 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 V4+, many of these classes and interfaces have been moved into the public API.

In practice, the data connector may be supplied with Spring-defined beans of the following types:

Spring Example

Example of a springResources file
<!-- In this case the definition would be <DataConnector" xsi:type="LDAPDatabase" springResources="....." /> --> 
<?xml version="1.0" encoding="UTF-8"?>
<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"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsd">

    <!-- each bean is set on LDAPDataConnector -->
    <bean class="org.ldaptive.pool.PooledConnectionFactory">
        <property name="connectionPool">
            <bean class="org.ldaptive.pool.BlockingConnectionPool" init-method="initialize" p:blockWaitTime="${connectionPool.blockWaitTime}">
                <constructor-arg index="0">
                    <bean class="org.ldaptive.pool.PoolConfig"
                        p:minPoolSize="%{idp.pool.LDAP.minSize}"
                        p:maxPoolSize="%{idp.pool.LDAP.maxSize}"
                        p:validateOnCheckIn="%{idp.pool.LDAP.validateOnCheckin}"
                        p:validateOnCheckOut="%{idp.pool.LDAP.validateOnCheckout}"
                        p:validatePeriodically="%{idp.pool.LDAP.validatePeriodically}"
                        p:validatePeriod="%{idp.pool.LDAP.validatePeriod}" />
                </constructor-arg>
                <constructor-arg index="1">
                    <bean class="org.ldaptive.DefaultConnectionFactory">
                        <property name="connectionConfig">
                            <bean class="org.ldaptive.ConnectionConfig" p:ldapUrl="%{idp.attribute.resolver.LDAP.ldapURL}"
                                p:connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
                                p:responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}"
                                p:useSSL="%{idp.attribute.resolver.LDAP.useSSL}"
                                p:useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS}">
                                <property name="connectionInitializer">
                                    <bean class="org.ldaptive.BindConnectionInitializer"
                                        p:bindDn="%{idp.attribute.resolver.LDAP.bindDN}"
                                        p:bindCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}" />
                                </property>
                                <property name="sslConfig">
                                    <bean class="org.ldaptive.ssl.SslConfig">
                                        <property name="credentialConfig">
                                            <bean class="org.ldaptive.ssl.X509CredentialConfig"
                                                p:trustCertificates="%{idp.attribute.resolver.LDAP.trustCertificates}"
                                                p:authenticationCertificate="%{idp.attribute.resolver.LDAP.authCertificate}"
                                                p:authenticationKey="%{idp.attribute.resolver.LDAP.authKey}" />
                                        </property>
                                    </bean>
                                </property>
                            </bean>
                        </property>
                    </bean>
                </constructor-arg>
                <property name="validator">
                    <bean class="org.ldaptive.pool.SearchValidator">
                        <property name="searchRequest">
                            <bean class="org.ldaptive.SearchRequest">
                                <constructor-arg value="%{idp.pool.LDAP.validatorBaseDN}" />
                                <constructor-arg value="%{idp.pool.LDAP.validatorFilter}" />
                            </bean>
                        </property>
                    </bean>
                </property>
                <property name="pruneStrategy">
                    <bean class="org.ldaptive.pool.IdlePruneStrategy"
                        p:prunePeriod="%{idp.pool.LDAP.prunePeriod}"
                        p:idleTime="%{idp.pool.LDAP.idleTime}" />
                </property>
            </bean>
        </property>
    </bean>

    <bean class="org.ldaptive.SearchExecutor"
        p:baseDn="%{idp.attribute.resolver.LDAP.baseDN}"
        p:returnAttributes="%{idp.attribute.resolver.LDAP.returnAttributes}" />

    <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.ldap.impl.TemplatedExecutableSearchFilterBuilder"
        p:templateText="%{idp.attribute.resolver.LDAP.searchFilter}" p:velocityEngine-ref="shibboleth.VelocityEngine"
        init-method="initialize" />
</beans>
  • No labels