Json2Ldap

Configuration

Json2Ldap is configured by a set of parameters in the WEB-INF/web.xml file in the web application archive (WAR).

Incoming client connection settings Outgoing LDAP connection settings
Default connection parameters Logging
Custom trust and key store settings for outgoing TLS/SSL LDAP connections

Remember to restart your web server after making changes to the Json2Ldap configuration!

You can also have a look at the initial configuration that Json2Ldap is shipped with.

1. Incoming client connection settings

The json2ldap.clients.* set of parameters controls the client access to the Json2Ldap gateway / proxy and by extension the back-end directory servers. This includes parameters for requiring HTTPS access or bind authentication, for filtering requests according to their type and for establishing quotas and time limits on the LDAP connections.

json2ldap.clients.requireAuthentication

Set to true to require clients to authenticate to the directories at connection time with a bind DN and password; any requests for an anonymous rebind thereafter will be refused. If the initial bind request fails the LDAP connection will be closed immediately.

Set to false to allow the relay of anonymous and unauthenticated LDAP requests to the directory servers.

You can use this setting to block the relay of anonymous LDAP requests to the directory servers. In addition, this allows to guard against denial-of-service (DoS) attacks by malicious unauthenticated clients which may otherwise saturate the LDAP servers with too many open anonymous connections.

json2ldap.clients.requireSecureAccess

Set to true to require all clients to connect via HTTP secure (HTTPS) to the Json2Ldap gateway/proxy. Requests received via plain HTTP will be refused.

Set to false to allow unencrypted connections to Json2Ldap.

Requiring HTTPS guards against eavesdropping on sensitive data between the clients and the Json2Ldap gateway/proxy.

json2ldap.clients.denyWriteRequests

Set to true to refuse all requests for LDAP write operations such as add, delete and modify.

Set to false to allow write requests to be relayed to the LDAP servers.

You can disable write access if the Json2Ldap clients are not expected to modify data on the directory servers.

json2ldap.clients.denyReadRequests

Set to true to refuse all requests for LDAP read operations such as ldap.getEntry, ldap.compare and ldap.search.

Set to false to allow read requests to be relayed to the LDAP servers.

You may disable read access in special cases when the Json2Ldap clients will be using the directories for authentication only (via a bind operation).

json2ldap.clients.denyBindRequests

Set to true to refuse all requests for LDAP simple bind (authentication with DN and password) to the directory servers.

Set to false to allow simple bind requests to be relayed to the LDAP servers.

You can disable simple bind request relay if the Json2Ldap clients will be using the directories for retrieval of public information only and want to guard against password guessing attacks.

json2ldap.clients.denyPasswordModifyRequests

Set to true to refuse all ldap.ext.passwordModify requests for the Password Modify extended operation (RFC 3062).

Set to false to allow Password Modify requests to be relayed to the LDAP servers.

You may choose to block Password Modify requests to prevent Json2Ldap clients from changing their directory passwords. Note that clients may still be able to alter their password with a regular LDAP modify request, see json2ldap.clients.denyWriteRequests for refusing LDAP write operations.

json2ldap.clients.denyWhoAmIRequests

Set to true to refuse all ldap.ext.whoAmI requests for the "Who am I?" extended operation (RFC 4532).

Set to false to allow "Who am I?" requests to be relayed to the LDAP servers.

json2ldap.clients.connectionQuotaPerIP

Specifies the maximum number of LDAP connections that a Json2Ldap client at a certain IP address may have. Further connection requests from the same IP address will be denied until an existing connection is closed or expires.

Set to 0 to lift this restriction.

You can use this setting as a protection against denial-of-service (DoS) attacks by malicious clients which may otherwise saturate the LDAP servers with too many open connections.

json2ldap.clients.connectionQuotaPerBindDN

Specifies the maximum number of LDAP connections bound (authenticated) as a certain DN. Further connection requests will be denied until the existing connections are closed or expire.

Set to 0 to lift this restriction.

You can use this setting as a protection against denial-of-service (DoS) attacks by malicious clients which may otherwise saturate the LDAP servers with too many open connections.

json2ldap.clients.maxIdleTime

Specifies the maximum idle time in minutes for LDAP connections. Connections that remain unused for longer will be automatically closed.

Note that the LDAP server may enforce a shorter idle time, causing an inactive connection to be closed before that.

Recommended value 15 minutes.

json2ldap.clients.maxConnectionTime

Specifies the maximum LDAP connection time in minutes. Connections that reach this time limit will be automatically closed.

Note that the LDAP server may enforce a shorter connection time, causing a connection to be closed before that.

Recommended value 300 minutes (5 hours).

2. Outgoing LDAP connection settings

The json2ldap.ldap.* set of parameters places important controls on the outgoing LDAP connections to the directory servers.

json2ldap.ldap.allowedServers

List of the LDAP servers that the Json2Ldap gateway will allow connecting to, specified as whitespace separated LDAP URLs containing a hostname/IP address and an optional port number. If the port number is left out, a default value will be assumed, typically 389 for plain and TLS connections (ldap://) or 636 for SSL connections (ldaps://). Connect requests to servers not contained in this list will be refused.

Set to * (asterisk) to allow connect requests to any LDAP server.

Example: List 3 LDAP servers by name or IP address, the last one specifying a non-default port number:

ldap://directory.mydomain.com
ldap://192.168.0.1 
ldap://ds.mydomain.com:1389

The purpose of this whitelist is to prevent arbitrary use of the Json2Ldap gateway/proxy by web clients.

json2ldap.ldap.requireSecureAccess

Set to true to require all connections from the Json2Ldap gateway/proxy to the LDAP servers to be secured through TLS or SSL. Requests for unencrypted LDAP connections will be refused.

Set to false to allow unencrypted connections from the Json2Ldap gateway/proxy to the LDAP servers.

Enable this setting to guard against eavesdropping on sensitive data between the Json2Ldap gateway/proxy and the LDAP servers.

json2ldap.ldap.autoReconnect

Set to true to attempt to automatically reconnect to the LDAP server if the connection is lost. This feature is only available for authenticated connections that support re-binding on a new connection.

Set to false to disable automatic reconnecting.

3. Default connection settings

This set of parameters defines the default LDAP connection to make when Json2Ldap receives an ldap.connect request where a server host has not been specified. Clients can make use of such requests to connect to a predefined directory server without knowing its network address, port and security details.

json2ldap.defaultConnection.enable

Set to true to enable clients to connect to a default LDAP server by making an ldap.connect request with omitted server parameters. Otherwise set to false.

If you set this to true you must also specify the connection details for the default LDAP server (see below).

json2ldap.defaultConnection.server

The LDAP server for default ldap.connect requests.

The value must be an LDAP URL specifying the server host name/IP address and port number. Valid ports are integers from 1 to 65535, if omitted a default value is taken, typically port 389 for plain and TLS connections or port 636 for SSL connections.

Example:

ldap://dir.mydomain.com:1389

json2ldap.defaultConnection.timeout

The timeout in milliseconds for default ldap.connect requests. Set to 0 to let the underlying LDAP client library and operating system determine the connection request timeouts.

json2ldap.defaultConnection.security

The transport security for default ldap.connect requests. Accepted values are none, SSL and StartTLS.

Set to none to establish a plain insecure connection.

Set to SSL to establish a secure connection over SSL.

Set to StartTLS to establish a secure connection using the StartTLS protocol (recommended method).

json2ldap.defaultConnection.trustSelfSignedCerts

Set to true to trust self-signed certificates presented by the default LDAP server (applies to default connections with security set to SSL or StartTLS.

Normally, only certificates signed by a trusted certificate authority (CA) should be accepted; self-signed certificates should be rejected.

4. Custom trust and key store settings for outgoing TLS/SSL LDAP connections

The json2ldap.ldap.customTrustStore.* and json2ldap.ldap.customKeyStore.* sets of parameters allow to specify custom trust and key stores (apart from those provided by the underlying JVM) to establish the security context of TLS/SSL connections between Json2Ldap and the back-end LDAP directories.

json2ldap.ldap.customTrustStore.enable

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

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

json2ldap.ldap.customTrustStore.file

The location of the custom trust store file.

Example:

WEB-INF/truststore.jks

json2ldap.ldap.customTrustStore.type

The type of the trust store file, typically JKS or PKCS12.

Set to an empty string to assume the system default type.

json2ldap.ldap.customTrustStore.password

The password required to unlock the trust store file.

Set to an empty string if none is required.

json2ldap.ldap.customKeyStore.enable

Set to true to use your custom key store file for client security certificates to be presented to remote LDAP servers 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).

json2ldap.ldap.customKeyStore.file

The location of the custom key store file.

Example:

WEB-INF/keystore.jks

json2ldap.ldap.customKeyStore.type

The type of the trust store file, typically JKS or PKCS12.

Set to an empty string to assume the system default type.

json2ldap.ldap.customKeyStore.password

The password required to unlock the key store file.

Set to an empty string if none is required.

5. Logging

Json2Ldap uses the popular Log4j framework to handle logging. The WEB-INF/web.xml contains just a single context parameter related to logging - it points to the location of the Log4j properties file where the actual behaviour of the logging subsystem is configured.

json2ldap.log4j.configurationFile

The location of the Log4j properties file, as an absolute path or relative to the web application root directory.

If no file location is specified logging is disabled.

Json2Ldap comes with a default Log4j properties file WEB-INF/log4j.properties.