Nimbus Directory Services

Json2Ldap Configuration

Json2Ldap allows for comprehensive configuration through a set of parameters in the WEB-INF/web.xml descriptor file. You may edit the original configuration to change the default web service behaviour. Remember to restart your web server when you're done for the modified configuration to take effect.

Client interface » LDAP connections »

Parameters for managing web client access: authentication, security, LDAP request filtering, session times and quotas.

Parameters for managing the outgoing LDAP connections: directory server whitelists, security, auto-reconnect.
Default LDAP connection »

For specifying a default directory server for ldap.connect requests.
Custom trust / key store for TLS/SSL LDAP » SRP-6a authentication »

For setting a custom trust or key store for outgoing TLS/SSL LDAP connections.

For setting Secure Remote Password (SRP-6a) authentication to the default LDAP server.
In-memory directory server » Cross-Origin Resource Sharing (CORS) »

For setting up a simple in-memory directory server for demonstration and testing purposes.

Parameters for managing browser cross-domain requests using the CORS mechanism.
Logging »

Log4j configuration file location.

1. Client interface

The json2ldap.clients.* parameters configure the web client access policy. This includes parameters for making HTTPS access or user authentication mandatory, for filtering LDAP requests according to their type and for establishing quotas and time limits on client sessions.

json2ldap.clients.requireAuthentication

Set to true to require all Json2Ldap clients to authenticate to the directories at connection time through one of the available bind mechanisms (simple, plain SASL, etc.); 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 HTTP secure (HTTPS) for all client connections to Json2Ldap. Requests received via plain HTTP will be refused.

Set to false to allow unsecured client connections to Json2Ldap.

The purpose of enforcing HTTPS access is to guard against eavesdropping on sensitive data exchanged between Json2Ldap and its web clients.

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 get entry, compare and 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 bind (authentication) to the directory servers.

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

You can disable LDAP bind request relay if the Json2Ldap clients will be using the directories for retrieval of public information only and also want to guard against potential 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 might 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 originating from a single client IP address. 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.connectionQuotaPerUser

Specifies the maximum number of LDAP connections per authenticated user identity (user DN). Further connection requests 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.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 exceed 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 600 minutes (10 hours).

json2ldap.clients.responseContentType

Sets the value of the HTTP "Content-Type" header for the JSON-RPC 2.0 responses.

Set to text/plain if you intend to support browser CORS requests, else set to application/json.

json2ldap.clients.reportRequestProcTime

Set to true to enable reporting of request processing time by appending a non-standard "xProcTime" attribute to the JSON-RPC 2.0 responses.

Intended for debugging and testing purposes. Disabled by default to prevent parse exceptions by clients which don't allow unexpected JSON attributes in the JSON-RPC 2.0 response messages.

Example JSON-RPC 2.0 response message with the xProcTime attribute turned on:

{ 
  "result"    : "2011-08-06T18:44:06+00:00",
  "xProcTime" : "15743 us",
  "id"        : 1,
  "jsonrpc"   : "2.0"
}

2. LDAP connections

The json2ldap.ldap.* parameters place important controls on the LDAP connection from Json2Ldap to the back-end directories.

json2ldap.ldap.allowedServers

List of the LDAP servers that the Json2Ldap 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 clients from establishing connections to arbitrary LDAP servers.

json2ldap.ldap.requireSecureAccess

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

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

Enable this setting to guard against eavesdropping on sensitive data between the Json2Ldap 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 LDAP connection

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 "host" parameter. 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://ds.mydomain.com:10389

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 for TLS/SSL LDAP

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 Java runtime) 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. Secure Remote Password (SRP-6a) authentication

Secure Remote Password (SRP) is an ingenious authentication method where the password remains private to the user at all times and never has to be communicated beyond their computer; instead, what client and server exchange is a series of cryptographically secured messages. SRP is resistant to eavesdropping and man-in-the-middle attacks. It can be used as a drop-in replacement for conventional weak password authentication methods.

Since SRP for LDAP directories has not been standardised yet, Json2Ldap implements it by acting as an authenticating proxy (or middleman). SRP authentication can be enabled for default LDAP connections, by setting up a special Json2Ldap service account and specifying an entry attribute to store the user SRP credentials (salt 's' and verifier 'v').

Json2Ldap implements the most recent 6a version of the Secure Remote Password (SRP) protocol. The implementation is based on the Nimbus SRP library.

json2ldap.x.srp6.enable

Set to true to enable SRP-6a authentication for default LDAP connections.

Set to false to disable SRP-6a authentication.

json2ldap.x.srp6.dn

The distinguished name (DN) under which the SRP extension will operate. It must be granted the following directory privileges:

Example:

cn=json2ldap,ou=web services,dc=wonderland,dc=net

json2ldap.x.srp6.password

The password for the distinguished name (DN) under which the SRP extension will operate.

json2ldap.x.srp6.attribute

The directory attribute for storing the SRP-6a user credentials: the salt 's' and the password verifier 'v'.

The credentials will be stored in the following format:

salt-hex-string;verifier-hex-string

Example attribute:

srp6Verifier

You may use the following schema for storing the SRP-6a user credentials. It defines an object class srp6Account which can be attached to any directory entry to enable SRP-6a authentication for it.

json2ldap.x.srp6.primeSize

The preferred bitsize of the prime number used for the modulus 'N' parameter. Json2Ldap supports a set of precomputed safe primes with 256, 512, 768 and 1024 bits.

The default prime 'N' size is 256 bits:

256

json2ldap.x.srp6.saltSize

The preferred byte size of the salt 's'.

The default salt 's' size is 16 bytes:

16

json2ldap.x.srp6.hashAlgorithm

The preferred hash algorithm. Must be supported by the underlying Java runtime.

Standard algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512.

The default hash algorithms 'H' is SHA-1:

SHA-1

json2ldap.x.srp6.timeout

The SRP-6a authentication session timeout in seconds. If an authenticating client fails to respond within the specified time the session must be closed by Json2Ldap.

The default timeout is 300 seconds (or 5 minutes):

300

6. In-memory directory server

Since version 1.9 Json2Ldap includes a simple in-memory directory server by UnboundID Corp. The server can be enabled for demonstration and testing purposes. It can be accessed in two ways:

If enabled, access to the in-memory directory server is limited to read and bind (authenticate) only. So after the directory is populated with the initial data no further changes can be made to it.

The in-memory directory server is configured by the inMemoryDirectoryServer.* parameters.

inMemoryDirectoryServer.enable

Set to true to enable the simple in-memory directory server for Json2Ldap demonstration and testing purposes. Access is limited to read and bind (authenticate) only. If enabled you must also specify the additional server details below.

Set to false to disable the in-memory directory server.

inMemoryDirectoryServer.port

The port number on which the in-memory directory server accepts LDAP client connections. SSL and StartTLS connections are not supported at present.

Set to zero to let the server automatically select an available port which will be recorded in the Json2Ldap log.

Note that the server may require a special OS permission to use a privileged port number below 1024.

Example:

10389

inMemoryDirectoryServer.schema

Specifies an alternative schema for the in-memory directory server. The alternative schema must be supplied in a single LDIF file. Its location must be an absolute path or relative to the web application home directory.

If undefined the default built-in server schema will be used.

Example:

WEB-INF/schema.ldif

inMemoryDirectoryServer.baseDN

The base distinguished name (DN) of the directory information tree. It must match the top level entry of the content LDIF (if supplied).

Example:

dc=wonderland,dc=net

inMemoryDirectoryServer.content

Reads entries from the specified LDIF file to populate the directory tree. The location of the file must be an absolute path or relative to the web application home directory.

If undefined the directory will be left empty.

Json2Ldap comes with a simple demo LDIF file which specifies a directory tree with 26 person entries and 4 groups.

Example:

WEB-INF/demo.ldif

7. Cross-Origin Resource Sharing (CORS)

The Json2Ldap web service includes a CORS Filter to allow transparent handling of browser cross-site requests according to the W3C Cross-Origin Resource Sharing (CORS) mechanism. To configure the CORS policy edit the init-params of the CORS filter entry in the WEB-INF/web.xml descriptor.

cors.allowGenericHttpRequests

Set to true to allow generic HTTP requests, else only valid and accepted CORS requests will be allowed (strict CORS filtering).

Recommended value: true

cors.allowOrigin

Lists the allowed CORS origins. They must be specified as whitespace-separated URLs. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to * all origins will be allowed.

cors.supportedMethods

Lists the supported HTTP methods. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.

Json2Ldap supports only GET and POST. Do not change this parameter.

cors.supportedHeaders

Lists the supported non-simple (according to the CORS standard) header names.

Applications that wish to specify an application/json request content type should be allowed so.

Recommended value: Content-Type

cors.exposedHeaders

Lists the non-simple headers (according to the CORS standard) that the web client (browser) should expose.

Json2Ldap sets a custom X-Web-Service header to identify itself. Do not change this parameter.

cors.supportsCredentials

Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported.

Json2Ldap doesn't support such user credentials. Do not change this parameter.

cors.maxAge

Indicates how long the results of a CORS preflight request can be cached by the web client, in seconds. If -1 unspecified.

Recommended value: 1 day (86400 seconds).

8. Logging

Json2Ldap uses the popular Log4j framework to handle logging. The WEB-INF/web.xml file 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 home directory.

If no file location is specified logging is disabled.

The default Log4j properties file is WEB-INF/log4j.properties.