Json2Ldap Add-ons

This page features add-ons designed to extend the Json2Ldap web API with helpful features.

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 7+
• Json2Ldap 3.x +

Installation

1. Download the latest stable add-on version.

2. Put the JAR package in the WEB-INF/lib directory of the Json2Ldap WAR file (json2ldap.war):

   WEB-INF/lib/json2ldap-proxy-connect-1.2.jar
   

3. Add the following lines to the web.xml descriptor of the Json2Ldap WAR (json2ldap.war), after the CORS filter declaration:

   <filter>
       <filter-name>ProxiedLdapConnect</filter-name>
       <filter-class>com.nimbusds.json2ldap.addons.proxyconnect.ProxiedLDAPConnectFilter</filter-class>
       <init-param>
           <description>
               The location of the proxy connect configuration file. Must be
               relative to the web application root directory.
           </description>
           <param-name>proxyConnect.configurationFile</param-name>
           <param-value>/WEB-INF/proxyConnect.json</param-value>
       </init-param>
   </filter>
   
   <filter-mapping>
       <filter-name>ProxiedLdapConnect</filter-name>
       <servlet-name>Json2LdapServlet</servlet-name>
   </filter-mapping>
   

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

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