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.

See ldap.ext.passwordModify.

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

Json2Ldap Add-ons

1. Proxied connect / bind add-on

Use case

System requirements

Installation

Configuration

Usage

Filtering Password Modify (RFC 3062) Extended Operations

2. Password encryption add-on

Use case

System requirements

Installation

Use

Encryption operation and parameters

Json2Ldap

Contact

PRODUCTS

OPEN SOURCE

LEARN

PRODUCTS

OPEN SOURCE

LEARN