Configuration

Configuration methods

Json2Ldap is configured by a simple properties (key / value) file located in the WEB-INF directory of the distributed WAR package:

• /WEB-INF/json2ldap.properties (click to view)

Edit the configuration file to change the default settings for client access, request filtering and LDAP server connections.

Alternatively, every file-based configuration property can be overridden by a Java system property. A system property can be set with the -D Java command line argument like this:

-Djson2ldap.access.https.require=true

To pass a list of Java system properties to an Apache Tomcat server set the CATALINA_OPTS environment variable:

export CATALINA_OPTS="$CATALINA_OPTS -Djson2ldap.access.https.require=true -Djson2ldap.api.denyWriteRequests=true"

Caveat: Characters that have a special meaning in the shell, such as & and ;, must be escaped. Whitespace must be avoided or escaped, for instance make sure there is no whitespace around the = and in lists.

Remember to restart your Json2Ldap service instance for the modified configuration to take effect.

Configuration overview

Additional configurations are available for the sample LDAP directory server, for handling cross-domain (CORS) requests and for controlling logging.

Access control

The json2ldap.access.* properties specify the access control policy of Json2Ldap. They allow the creation of access rules based on HTTPS security, X.509 client certificate, client IP address, and / or API keys.

json2ldap.access.https.require

If true requires clients to connect using HTTP secure (HTTPS). Plain HTTP connections will be denied with a “Requests must be sent over HTTPS” (-31100) error.

It’s recommended that HTTPS use is enforced at all times to prevent eavesdropping on user credentials and details:

json2ldap.access.https.require = true

json2ldap.access.https.requireClientCert

If true requires clients to authenticate with a valid X.509 certificate issued by a trusted certificate authority (CA). This forces the mutual authentication of both server and client in the HTTPS connection. HTTPS requests without a valid client certificate will be denied with a “Trusted client X.509 certificate required” (-31110) error.

json2ldap.access.https.requireClientCert = true

json2ldap.access.https.clientCertPrincipal

If specified, requires the X.509 client certificate subject to match the specified distinguished name (DN). Client certificates with a non-matching subject (principal) will be denied with a “Client X.509 certificate principal denied” (-31112) error.

json2ldap.access.https.clientCertPrincipal = CN=json2ldapClient, OU=apps, DC=wonderland, DC=net

json2ldap.access.hosts.allow

Space-separated list of client IPs and / or hostnames that are allowed access to Json2Ldap. If set to * (asterisk) any IP address is allowed. Requests from non-matching client IPs / hostnames will be denied with a “Client IP address denied access” (-31105) error.

Example: Allow access from any IP address:

json2ldap.access.hosts.allow = *

Example: Allow only the two listed client IP addresses:

json2ldap.access.hosts.allow = 192.168.0.1 192.168.0.2 192.168.0.3

json2ldap.access.apiKeys.require

If true web clients must present an API key with each JSON-RPC 2.0 request. The API key is passed through the optional string parameter named apiKey. Requests without an API key will be denied with an “Missing API key” (-31121) error. Requests with an invalid API key will be denied with an “API key denied access” (-31123) error.

Example Json2Ldap request with an API key:

{
  "method"  : "ldap.connect",
  "params"  : { "apiKey" : "f70defbeb88141f88138bea52b6e1b9c" },
  "id"      : 1,
  "jsonrpc" : "2.0"
}

If false API keys will not be required for json2ldap access.

json2ldap.access.apiKeys.require = true

json2ldap.access.apiKeys.exemptedMethods

Space-separated list of names of exempted JSON-RPC 2.0 methods for which an API key is not required. All other methods will require an API key to be presented.

To allow public access to the ws.getName, ws.getVersion and ws.getTime Json2Ldap requests:

json2ldap.access.apiKeys.exemptedMethods = ws.getName ws.getVersion ws.getTime

json2ldap.access.apiKeys.map.*

Map of API keys to the JSON-RPC 2.0 methods they are allowed access to. Asterisk (*) signifies any method is allowed for the given API key.

The API key strings should be random and of sufficient length to prevent their guessing. An UUID generator can be used for this purpose.

Example map defining two API keys and the corresponding allowed Json2Ldap requests:

API key one:

• API key: f70defbeb88141f88138bea52b6e1b9c
• Allowed requests: ldap.connect, ldap.close, ldap.search

API key two:

• API key: 08d1e641b1c14d888796e47c06430efb
• Allowed requests: any

json2ldap.access.apiKeys.map.f70defbeb88141f88138bea52b6e1b9c = ldap.connect ldap.close ldap.search
json2ldap.access.apiKeys.map.08d1e641b1c14d888796e47c06430efb = *

Web API settings

The json2ldap.api.* parameters enable / disable specific calls and options in the Json2Ldap web API. The preferred HTTP response content type is also set here.

json2ldap.api.requireAuthentication

Set to true to require Json2Ldap clients to authenticate to the directory 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 server.

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.

User authentication is not required by default:

json2ldap.api.requireAuthentication = false

json2ldap.api.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 directory servers.

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

Write access is allowed by default:

json2ldap.api.denyWriteRequests = false

json2ldap.api.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 directory 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).

Read access is allowed by default:

json2ldap.api.denyReadRequests = false

json2ldap.api.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 directory 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.

Bind (authentication) is allowed by default:

json2ldap.api.denyBindRequests = false

json2ldap.api.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 directory servers.

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

json2ldap.api.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 directory servers.

json2ldap.api.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.

To cap LDAP connections per client IP at ten:

json2ldap.api.connectionQuotaPerIP = 10

json2ldap.api.connectionQuotaPerUser

Specifies the maximum number of LDAP connections per authenticated user identity (authzId or 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.

To cap LDAP connections per user at five:

json2ldap.api.connectionQuotaPerUser = 5

json2ldap.api.disableErrorCodeMapping

Set to true to disable the JSON-RPC 2.0 error to HTTP status code mapping introduced in Json2Ldap 3.5 and revert to the HTTP 200 status code from previous versions. The default value is ‘false’.

To revert to pre 3.5 behaviour:

json2ldap.api.disableErrorCodeMapping = true

json2ldap.api.exposeExceptions

This setting controls reporting of details in JSON-RPC 2.0 “Internal error” messages (code -32603).

If true Json2Ldap will expose the cause of the exception in the “data” field of the JSON-RPC 2.0 error. Use this setting for debugging or if the web clients are trusted.

If false Json2Ldap will not provide any additional information about server exceptions. The exact cause can be found out in the Json2Ldap log. Use this setting if the web clients are not trusted or they don’t need to know any details about encountered exceptions.

To allow your web clients to inspect the cause of Json2Ldap exceptions:

json2ldap.api.exposeExceptions = true

json2ldap.api.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"
}

json2ldap.api.responseContentType

Sets the value of the HTTP “Content-Type” header for the JSON-RPC 2.0 responses. The character set option must be explicitly set to UTF-8.

The default content type is application/json:

json2ldap.api.responseContentType = application/json; charset=utf-8

To support cross-domain requests from older Internet Explorer 8 and 9 browsers which implement CORS partially set the content type to text/plain. See the MSDN article for further explanation.

json2ldap.api.responseContentType = text/plain; charset=utf-8

LDAP connections

The json2ldap.ldap.* parameters place important controls on the LDAP connections that Json2Ldap establishes to the back-end directories.

json2ldap.ldap.allowedServerURLs

List of the LDAP servers that the Json2Ldap will allow connecting to, specified as space 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 found 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:

json2ldap.ldap.allowedServerURLs = 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 Json2Ldap to the LDAP servers to be secured by means of StartTLS or SSL. Requests for unencrypted LDAP connections will be refused.

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

Enable this setting to guard against eavesdropping on sensitive data between the Json2Ldap and the LDAP servers:

json2ldap.ldap.requireSecureAccess = true

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:

json2ldap.ldap.autoReconnect = false

json2ldap.ldap.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.

To set the idle time at 15 minutes:

json2ldap.ldap.maxIdleTime = 15

json2ldap.ldap.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.

To set the max connection time to 600 minutes (10 hours):

json2ldap.ldap.maxConnectionTime = 600

Default LDAP server

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 preset directory server without knowing its network address, port and security details.

json2ldap.defaultLDAPServer.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.defaultLDAPServer.enable = true

json2ldap.defaultLDAPServer.url

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:

• For ldap: (plain and StartTLS connections) this is port 389.

• For ldaps: (SSL connections) this is port 636.

Example:

json2ldap.defaultLDAPServer.url = ldap://ds.mydomain.com:10389

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

To specify a primary and failover LDAP server:

json2ldap.defaultLDAPServer.url = ldap://primary-ldap.mydomain.com ldap://secondary-ldap.mydomain.com

json2ldap.defaultLDAPServer.selectionAlgorithm

The preferred server selection algorithm in case json2ldap.defaultLDAPServer.url is an LDAP server set.

If set to FAILOVER Json2Ldap will attempt to 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.

If set to ROUND-ROBIN Json2Ldap will 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 LDAP server failover:

json2ldap.defaultLDAPServer.selectionAlgorithm = FAILOVER

To specify round-robin server selection:

json2ldap.defaultLDAPServer.selectionAlgorithm = ROUND-ROBIN

json2ldap.defaultLDAPServer.security

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

• Set to none to establish plain insecure connections.

• Set to SSL to establish secure connections over SSL.

• Set to StartTLS to establish secure connections using the StartTLS protocol (recommended method).

json2ldap.defaultLDAPServer.security = StartTLS

json2ldap.defaultLDAPServer.connectTimeout

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.defaultLDAPServer.connectTimeout = 0

json2ldap.defaultLDAPServer.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:

json2ldap.defaultLDAPServer.trustSelfSignedCerts = false

Custom trust and key store for TLS/SSL LDAP

The json2ldap.ldap.customTrustStore.* and json2ldap.ldap.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.

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:

json2ldap.ldap.customTrustStore.file = 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:

json2ldap.ldap.customKeyStore.file = 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.

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 servers, 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 servers.

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:

• Read and modify access to the directory attribute holding the SRP-6a user credentials;

• Perform proxied authentication for all SRP-6a users by means of a plain SASL bind operation.

Example:

json2ldap.x.srp6.dn = 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:

json2ldap.x.srp6.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 bit size 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:

json2ldap.x.srp6.primeSize = 256

json2ldap.x.srp6.saltSize

The preferred byte size of the salt ‘s’.

The default salt ‘s’ size is 16 bytes:

json2ldap.x.srp6.saltSize = 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:

json2ldap.x.srp6.hashAlgorithm = 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):

json2ldap.x.srp6.timeout = 300

Sample directory server

A sample LDAP directory server is included in the Json2Ldap WAR to enable evaluation and testing of the service without an external directory. The sample directory is enabled / disabled and configured by the following properties file:

/WEB-INF/sampleDirectory.properties

If enabled, access to the sample 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.

sampleDirectoryServer.enable

Set to true to enable the sample directory server. 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 sample directory server.

sampleDirectoryServer.enable = true

sampleDirectoryServer.port

The port number on which the sample 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.

sampleDirectoryServer.port = 10389

sampleDirectoryServer.schema

Specifies an alternative schema for the sample directory server. The alternative schema must be supplied in a single LDIF file. Its location must be relative to the web application (WAR) root directory.

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

sampleDirectoryServer.schema = /WEB-INF/sampleDirectorySchema.ldif

sampleDirectoryServer.baseDN

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

sampleDirectoryServer.baseDN = dc=wonderland,dc=net

sampleDirectoryServer.content

Reads entries from the specified LDIF file to populate the directory tree. The location of the file must be relative to the web application (WAR) root directory.

If undefined the directory will be left empty.

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

sampleDirectoryServer.content = /WEB-INF/sampleDirectoryContent.ldif

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

To configure the CORS policy edit the following properties file in the WEB-INF directory of the web application:

WEB-INF/cors.properties

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 * any origin is allowed.

Example: Allow any origin:

cors.allowOrigin = *

Example: Allow cross-domain requests from the following three origins only:

cors.allowOrigin = http://example.com http://example.com:8080 https://secure.net

cors.allowSubdomains

If true the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name / IP address and optional port number).

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

Logging

Json2Ldap uses the popular Log4j framework for logging.

The Log4j configuration file is located in the WEB-INF directory of the web application:

WEB-INF/log4j.xml

The shipped log4j.xml includes two Java system property variables to quickly override the default logging level or the appender:

• log4j.loggers.root.level – Sets the logging level, e.g. to “debug”, “info”, “warn”, or “error”. The default level is “info”.

• log4j.loggers.root.appender – Sets the default logging appender. Set to “console” to log to the standard output. The default appender is “rolling-file” (see the log4j.xml for details).

Refer to the Log4j manual for how to edit the configuration file.