The Shibboleth IdP V4 software will leave support on September 1, 2024.

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 37 Next »

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 (conf/examples/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.

Property

Type

Default Authn Property

Function

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

Duration

idp.authn.LDAP.connectTimeout (defaults PT3S)

Connection timeout in milliseconds

idp.attribute.resolver.LDAP.responseTimeout

Duration

idp.authn.LDAP.responseTimeout (defaults PT3S)

Time to wait for response

idp.attribute.resolver.LDAP.connectionStrategy

Enumeration

ACTIVE_PASSIVE

Connection strategy to use when multiple URLs are supplied, one of ACTIVE_PASSIVE, ROUND_ROBIN, RANDOM

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 (authKey, authCert).

Examples

 conf/attribute-resolver.xml
<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

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