LDAP claims source

The Connect2id server comes with a ready connector for retrieving UserInfo and other claims about a user from an LDAP directory, such as Microsoft Active Directory, Novell eDirectory, OpenLDAP or OpenDJ.

To enable / disable or configure the LDAP claims source connector edit the following properties file in the WEB-INF directory of the web application:

WEB-INF/ldapClaimsSource.properties

The file contains configuration properties split into six sections:

1. General settings – to enable / disable the LDAP claims source.
2. LDAP server connection details – to set the LDAP server connection details.
3. LDAP user credentials – to set the LDAP server connection credentials.
4. LDAP search configuration – to set the LDAP search parameters, such as filter, for retrieving the user entries and attributes.
5. Custom LDAP server trust and key store – to set a custom certificate trust and / or key key for secure LDAP connections.

Any configuration file property can be overridden by setting a system-wide property with a matching key, e.g. by using the optional -D argument at JVM startup:

-Dop.ldapClaimsSource.enable=false

To set the mapping of the LDAP attributes to UserInfo claims edit the following JSON file:

ldapClaimsMap.json

The claims source SPI and the LDAP connector implementation are open sourced and yon use them to devise your own custom connectors (e.g. for an SQL database).

https://bitbucket.org/connect2id/openid-connect-claims-source-spi

https://bitbucket.org/connect2id/openid-connect-ldap-claims-source

1. General settings

Contains a single property to enable / disable the LDAP claims source.

op.ldapClaimsSource.enable

This boolean setting enables / disables the LDAP claims source.

To enable it:

op.ldapClaimsSource.enable = true

To disable it:

op.ldapClaimsSource.enable = false

2. LDAP server details

The op.ldapClaimsSource.server.* properties set the LDAP server connection details.

op.ldapClaimsSource.server.url

The LDAP URL of the directory server for sourcing the claims. The schema must be ldap or ldaps, it must specify a valid host name or IP address as well as the port number if a non-default is used.

If the directory is replicated across several LDAP servers for the purpose of failover or load-balancing, the value is a space-separated list of the corresponding LDAP URLs. Server selection is handled according to op.ldapClaimsSource.ldapServer.selectionAlgorithm.

Example single LDAP server URL pointing to the local host:

op.ldapClaimsSource.server.url = ldap://localhost:1389

Example list of two LDAP server URLs (for use in a failover or load-balancing configuration):

op.ldapClaimsSource.server.url = ldap://192.168.1.10:1389 ldap://192.168.1.11:1389

op.ldapClaimsSource.server.selectionAlgorithm

The preferred server selection algorithm in case op.ldapClaimsSource.server. url is an LDAP server set:

• FAILOVER – Establish connections to the LDAP servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third and so on.

• ROUND-ROBIN – Use a round-robin algorithm to select the LDAP server to which the connection should be established. Any number of servers may be included in the set and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the list.

To specify failover server selection:

op.ldapClaimsSource.server.selectionAlgorithm = FAILOVER

op.ldapClaimsSource.server.connectTimeout

The timeout in milliseconds for LDAP connect requests. If zero the underlying LDAP client library will handle this value.

To specify a connect timeout of 250 ms:

op.ldapClaimsSource.server.connectTimeout = 250

op.ldapClaimsSource.server.security

The LDAP connection security:

• NONE – Establish a plain insecure connection.

• SSL – Establish a secure connection over SSL.

• StartTLS – Establish a secure connection using the StartTLS protocol (recommended method).

To use StartTLS for LDAP connections:

op.ldapClaimsSource.server.security = StartTLS

op.ldapClaimsSource.server.trustSelfSignedCerts

Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections). Self-signed certificates are not trusted by default.

To reject self-signed certificates:

op.ldapClaimsSource.server.trustSelfSignedCerts = false

op.ldapClaimsSource.server.connectionPoolSize

The maximum LDAP connection pool size. The default value is five connections.

To create a pool for 5 LDAP connections:

op.ldapClaimsSource.server.connectionPoolSize = 5

op.ldapClaimsSource.server.connectionPoolMaxWaitTime

The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain an LDAP connection from the pool. A value of zero should be used to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.

To set the max LDAP connection pool wait time to 250ms:

op.ldapClaimsSource.server.connectionPoolMaxWaitTime = 250

op.ldapClaimsSource.server.connectionMaxAge

The maximum time in milliseconds that an LDAP connection in the pool may be established before it should be closed and replaced with another connection. A value of zero indicates that no maximum age should be enforced. Defaults to no maximum age (zero).

To disable LDAP connection expiration:

op.ldapClaimsSource.server.connectionMaxAge = 0

3. LDAP user details

The op.ldapClaimsSource.directory.user.* set the LDAP server connection credentials.

op.ldapClaimsSource.directory.user.dn

The distinguished name (DN) of the LDAP directory user to perform the claims retrieval operations. Must have search and read access to the directory branch containing the subject entries. An empty value implies an anonymous user.

Example user DN:

op.ldapClaimsSource.directory.user.dn = cn=Directory Manager

op.ldapClaimsSource.directory.user.password

The directory user password. An empty value implies an anonymous user.

Example password:

op.ldapClaimsSource.directory.user.password = secret

4. LDAP search configuration

The op.ldapClaimsSource.directory.* properties set the LDAP search parameters, such as filter, for retrieving the user entries and attributes.

op.ldapClaimsSource.directory.baseDN

The base distinguished name (DN) of the LDAP directory branch where the subject (user) entries are stored.

op.ldapClaimsSource.directory.baseDN = ou=people,dc=wonderland,dc=net

op.ldapClaimsSource.directory.scope

The LDAP search scope for the subject entries with respect to the base DN specified in op.ldapClaimsSource.directory.baseDN:

• ONE – indicates that only entries that are immediate subordinates of the base entry (but not the base entry itself) should be considered.

• SUB – Indicates that the base entry itself and any subordinate entries (to any depth) should be considered.

• SUBORDINATE_SUBTREE – Indicates that any subordinate entries (to any depth) below the base entry should be considered, but the base entry itself should not be considered, as described in draft-sermersheim-ldap-subordinate-scope.

op.ldapClaimsSource.directory.scope = ONE

op.ldapClaimsSource.directory.filter

The LDAP search filter to retrieve the subject entries. The %u placeholder will be substituted with the subject identifier (sub).

op.ldapClaimsSource.directory.filter = (uid=%u)

5. Custom LDAP server trust and key store

The op.ldapClaimsSource.customTrustStore.* and op.ldapClaimsSource.customKeyStore.* properties specify custom trust and key stores (apart from those provided by the underlying JVM) to establish the security context of TLS/SSL connections to the LDAP servers.

op.ldapClaimsSource.customTrustStore.enable

Set to true to use your custom trust store file for determining the acceptable security certificates presented by the remote LDAP server.

Set to false to use the default trust store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a trust store file, type and password (see the corresponding parameters below).

op.ldapClaimsSource.customTrustStore.enable = false

op.ldapClaimsSource.customTrustStore.file

The location of the custom trust store file.

Example:

op.ldapClaimsSource.customTrustStore.file = WEB-INF/truststore.jks

op.ldapClaimsSource.customTrustStore.password

The password required to unlock the trust store file. Leave it empty if none is required.

Example:

op.ldapClaimsSource.customTrustStore.password = secret

op.ldapClaimsSource.customTrustStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.ldapClaimsSource.customTrustStore.type = JKS

op.ldapClaimsSource.customKeyStore.enable

Set to true to use your custom key store file for client security certificates to be presented to the remote LDAP server requiring such authentication.

Set to false to use the default key store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a key store file, type and password (see the corresponding parameters below).

op.ldapClaimsSource.customKeyStore.enable = false

The location of the custom key store file.

Example:

op.ldapClaimsSource.customKeyStore.file = WEB-INF/keystore.jks

op.ldapClaimsSource.customKeyStore.password

The password required to unlock the key store file. Leave it empty if none is required.

Example:

op.ldapClaimsSource.customKeyStore.password =

op.ldapClaimsSource.customKeyStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.ldapClaimsSource.customKeyStore.type = JKS