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
|
|
| 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. The character set option must be explicitly set to UTF-8.
Set to text/plain;charset=utf-8 if you intend
to support browser CORS requests, else set to the standard
application/json;charset=utf-8.
application/json;charset=utf-8
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:
- 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:
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:
- Through the Json2Ldap web API.
- Directly, with a regular LDAP client such as Apache Directory Studio.
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.
