Json2Ldap Add-ons
This page features add-ons designed to extend the Json2Ldap web API.
1. Proxied connect / bind add-on
Use case
You want to give users or client apps the ability to connect and authenticate to an LDAP directory via Json2Ldap without exposing the LDAP server's connection details and credentials.
System requirements
- Java 8+
- Json2Ldap 3.x +
Installation
Download the latest stable add-on version.
Put the JAR package in the
WEB-INF/lib
directory of the Json2Ldap WAR file (json2ldap.war
):WEB-INF/lib/json2ldap-proxy-connect-1.4.jar
Put the required add-on configuration file (see below) in the WEB-INF directory of the Json2Ldap WAR file (
json2ldap.war
):WEB-INF/proxyConnect.json
Deploy the modified Json2Ldap WAR to your Java web server (Apache Tomcat, Jetty, etc).
Configuration
The add-on is configured by means of a simple JSON file which specifies the supported proxied LDAP connections and their bind (authentication) credentials.
The configuration is represented by a JSON array containing zero or more JSON objects where each JSON object represents the details of a proxied LDAP connection.
id {string} Unique identifier for the proxied LDAP connection. The string will be treated in a case-insensitive manner.
password {string} Password to access the proxied LDAP connection. The string is case sensitive.
params {object} JSON object containing the ldap.connect parameters for the proxied LDAP connection, as specified in the Json2Ldap web API reference for ldap.connect.
Example configuration for two proxied LDAP connections:
[
{ "id" : "server-1",
"password" : "secret",
"params" : { "host" : "localhost",
"port" : 10389,
"timeout" : 500,
"simpleBind" : { "DN" : "cn=Directory Manager",
"password" : "secret"
}
}
},
{ "id" : "server-2",
"password" : "secret",
"params" : { "host" : "192.168.0.1",
"port" : 10686,
"security" : "SSL",
"simpleBind" : { "DN" : "cn=Alice",
"password" : "secret"
}
}
}
]
Usage
A proxied LDAP connection can be made by sending an "ldap.proxyConnect" request to the JSON-RPC 2.0 endpoint of the Json2Ldap web service. The request accepts the following named parameters:
id {string} The identifier of the proxied LDAP connection, as specified in the proxyConnect.json configuration.
password {string} The matching password for the proxied LDAP connection, as specified in the proxyConnect.json configuration.
[ apiKey ] {string} Optional API key to pass to the proxied Json2Ldap ldap.connect request.
Example ldap.proxyConnect
request:
POST /json2ldap/ HTTP/1.1
Host: example.com
Content-Type: application/json
{
"method" : "ldap.proxyConnect",
"params" : { "id" : "server-1", "password" : "secret" },
"id" : "001",
"jsonrpc" : "2.0"
}
If the proxy credentials match, the add-on will rewrite the ldap.proxyConnect
request as an ldap.connect request, using the
configured parameters, and pass it on to the Json2Ldap core for further
processing.
The returned response will be a regular ldap.connect response.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"result" : { "CID" : "oPi35AQsYZV5OuZpjjZKoju7hfZhHck_0ysmji7jT6o"},
"id" : "001",
"jsonrpc" : "2.0"
}
The connection identifier (CID) can then be used to make subsequent requests to the Json2Ldap web API.
If the proxy credentials are invalid the add-on will return a -2000 "Bad proxy credentials" error.
Filtering Password Modify (RFC 3062) Extended Operations
The add-on is also programmed to block Password Modify (RFC 3062) extended requests that do not include a userID parameter. The userID must be explicitly set to the distinguished name (DN) of the LDAP user which password is to be changed.
2. Password encryption add-on
Use case
This Json2Ldap add-on enables sensitive JSON-RPC 2.0 request parameters, such as LDAP passwords in a ldap.connect or ldap.simpleBind request, to be passed from the client to the Json2Ldap web service in encrypted form, adding a second layer of confidentiality on top of the TLS (https) connection. A periodic key refresh and a nonce requirement guarantee the freshness of the encrypted parameters and prevent their replay.
System requirements
- Java 8+
- Json2Ldap 3.x +
Installation
Download the latest stable add-on version.
Put the decryptor JAR package in the
WEB-INF/lib
directory of the Json2Ldap WAR file (json2ldap.war
):WEB-INF/lib/json2ldap-jwe-decryptor-1.0.jar
Deploy the modified Json2Ldap WAR to your Java web server (Apache Tomcat, Jetty, etc).
Use
To encrypt a password or another Json2Ldap request parameter use the supplied
json2ldap-password-encrypt.jar
command line utility. It expects two
arguments:
- The URL of the Json2Ldap web service
- The value to encrypt
Example encryption of the password string "secret" for a Json2Ldap web service
at https://json2ldap.example.com/
:
java -jar json2ldap-password-encrypt.jar -url https://json2ldap.example.com/ -pw secret
When the -pw
switch is omitted password can be alternatively passed from a
file:
java -jar json2ldap-password-encrypt.jar -url https://json2ldap.example.com/ < password.txt
Or the standard input:
java -jar json2ldap-password-encrypt.jar -url https://json2ldap.example.com/
The command line utility will download the latest public RSA encryption from
the Json2Ldap jwks.json
endpoint (see below) and output the encrypted string
in JSON Web Encryption (JWE) format, with the jwe:
prefix.
Example encryption of the string "secret":
jwe:eyJlbmMiOiJBMTI4R0NNIiwibm9uY2UiOiJ4VDlnTFhPMjk1anlBSzJBRE5PaTJRIiwiYWxnIjo
iUlNBLU9BRVAtMjU2Iiwia2lkIjoiUnZIWmFLY0dpSFYxYTBCRTNKUk03NVpWSzlaaGJLZkhoQ0Y4al
NkZkFQSSJ9.YYlafso4z4NlMq5QOCVou7MBNyUVMI-_KD4FoFNo9tQlwCZoDcOl46OGdz57guRjoNLf
2FesRhBR31iNvT9npU2A-XU8uQl-yCrOe0stOelte7w7dzSpuCE7Wsbcyq4yMDkVHPU6IS6oGGekzcd
gX5L0iqx-ygkj3rO_rOMxdKvuQe9igJwX39r8wHCxapgrVifaE0VcfNjVVM_KvO6EoWZDRa7Leuf9n1
f-4tDQyt2kheliLU-HXZOq-uus07ZMlVKHLN7n6pn06H4U6fw_G5JgfEe2uGUOwNbg0MOYBmVVw62gH
1iIL62TmuTZt3x6HUA9c7P3ezOOlpNPa_igMw.tiknPjSEvVHtEIcl.x9rLGBhD.KUmnl4MAzVZhgyJ
IoopFrA
Insert the encrypted string in place of the plaintext parameter in a Json2Ldap request.
Example use of an encrypted password in the ldap.connect
request:
{ "method" : "ldap.connect",
"params" : { "host" : "directory.wonderland.net",
"port" : 389,
"security" : "StartTLS",
"simpleBind" : { "DN" : "cn=Directory Manager",
"password" : "jwe:eyJlbmMiOiJBMTI4R0NNI..." },
"id" : 1,
"jsonrpc" : "2.0" }
The encrypted password can be used also in the LdapSync
targetDirectory.user.password
configuration property.
Example:
export TARGET_DIR_JWE_PWD=`java -jar json2ldap-password-encrypt.jar \
-url https://json2ldap.example.com/ \
-pw $TARGET_DIR_PWD`
java -DsourceDirectory.user.password=$SOURCE_DIR_PWD \
-DtargetDirectory.user.password=$TARGET_DIR_JWE_PWD \
-jar ldapsync.jar sync.properties
Note, passwords must be re-encrypted before each Json2Ldap request or LdapSync invocation. An encrypted password string can be used only once and within 10 minutes of the encryption. This is done to ensure the freshness of the encryption and prevent the replay of a leaked encrypted password or entire web API request. Attempting to reuse an encrypted password or delaying its submission past the 10 minutes will cause the request to be rejected with an "Invalid JWE encrypted parameter" error and record a warning in the Json2Ldap logs.
Example warning on attempted replay:
2023-07-04T16:49:49,345 WARN [JWE0026] Detected nonce / JWE reuse: CLk8jTJDWc_9HG_f9g9rZQ
Encryption operation and parameters
The add-on creates a /jwks.json
endpoint which publishes an automatically
generated JSON Web Key (JWK) set of
public RSA 2048-bit encryption keys, to which plaintext parameters can be
encrypted with integrity protection. A new RSA key is generated every 5 minutes
and the oldest one is discarded.
- Encryption format: JSON Web Encryption (JWE)
- JWE header:
- alg: RSA-OAEP-256
- enc: A128GCM
- kid: The RSA key identifier
- nonce: 16-byte nonce to prevent replay, BASE64URL encoded
- JWE payload: the plaintext parameter value, e.g. LDAP password
The json2ldap-password-encrypt.jar
is programmed to automatically fetch the
latest public RSA key from the /jwks.json
endpoint and perform the necessary
encryption.
The add-on logs use and debug messages under the JWE
prefix.
Example log entries from the add-on:
2023-07-04T16:46:13,030 INFO [JWE0040] Generated RSA 2048 bit encryption key with ID Q8I2Uv9tnICcfCGzClsH_mfZm1hvLbJLVeqxHSCJqG4
2023-07-04T16:46:13,031 INFO [JWE0041] Scheduled RSA key refresh to run every 300000ms
2023-07-04T16:46:13,033 INFO [JWE0020] Scheduled JWE nonce purge to run every 600000ms
2023-07-04T16:46:13,033 INFO [JWE0021] Initialized JSON-RPC 2.0 parameter decryptor add-on
2023-07-05T11:33:32,612 INFO [JWE0031] Rewrote ldap.connect request with decrypted JWE
2023-07-05T11:34:34,991 INFO [JWE0010] Purged 7 expired nonces
2023-07-05T11:34:35,086 INFO [JWE0050] Generated new RSA 2048 bit encryption key with ID RvHZaKcGiHV1a0BE3JRM75ZVK9ZhbKfHhCF8jSdfAPI