Json2Ldap

Web API

Clients can send LDAP requests to the Json2Ldap web service using JSON-RPC 2.0 over HTTP (POST), the latest version of the simple protocol for remote procedure calls (RPC) with JSON encoded messages.

The Json2Ldap methods expect request parameters to be specified by name (as key-value pairs); positional parameters are not accepted. Using named parameters allows methods to have multiple optional parameters and makes it possible to introduce additional ones in future without breaking backward compatibility.

Clients start an LDAP session by requesting a connection to a specified directory server. Upon a successful connect Json2Ldap returns a connection identifier (CID) string which is used to reference the LDAP connection in subsequent directory requests. Clients should send a request to close the connection once they no longer need it; if not the connection will be closed automatically by Json2Ldap after a time value specified by the json2ldap.clients.maxIdleTime parameter.

Here is an example of a JSON-RPC 2.0 ldap.connect request to establish a plain connection to an LDAP server on host ldap.example.com that listens on port 1389.

{
  "method"  : "ldap.connect",
  "params"  : { "host" : "ldap.example.com", "port" : 1389 },
  "id"      : 1,
  "jsonrpc" : "2.0"
}

If the connect request is successful, Json2Ldap will return a JSON-RPC 2.0 response with the connection identifier (CID) representing the established LDAP connection. The CID value is contained in the result field of the response.

{
  "result"  : "74cd2a2b584f0535b1bfc5401c7ce2ed",
  "id"      : 1,
  "jsonrpc" : "2.0"
}

If, however, the connect request fails, a JSON-RPC 2.0 response with an error is returned. Here is an example error the client would get if Json2Ldap couldn't establish a network connection:

{
  "error"   : { "code"    : 1103,
                "message" : "LDAP server down or invalid host\/port" },
  "id"      : 1,
  "jsonrpc" : "2.0"
}

Once the connection is made, the client can send requests for various LDAP operations such as ldap.getEntry or ldap.search. The CID parameter must always be supplied, otherwise Json2Ldap wouldn't know which LDAP connection the client is referring to.

Here is an example of a ldap.getEntry request where the client wishes to retrieve the attributes of the directory entry with distinguished name (DN) uid=user.123,ou=People,dc=example,dc=com:

{
  "method"  : "ldap.getEntry",
  "params"  : { "CID" : "7af10fbb52ad093040bb58a7ca344206",
                "DN"  : "uid=user.123,ou=People,dc=example,dc=com" },
  "id"      : 2,
  "jsonrpc" :"2.0"
}

And the resulting example ldap.getEntry response:

{
  "result" : { "DN"              : "uid=user.123,ou=People,dc=example,dc=com",
               "objectClass"     : [ "top", 
                                     "person", 
                                     "inetorgperson", 
                                     "organizationalperson" ],
               "cn"              : ["Aili Aksel"],
               "sn"              : ["Aksel"],
               "uid"             : ["user.123"],               
               "mail"            : ["user.123@maildomain.net"],
               "telephoneNumber" : ["+1 558 831 4090"],
               "employeeNumber"  : ["123"] },
 "id"      : 1,
 "jsonrpc" : "2.0"
}

To close the LDAP connection send a ldap.close request to the Json2Ldap gateway/proxy.

{
  "method"  : "ldap.close",
  "params"  : { "CID":"7af10fbb52ad093040bb58a7ca344206" },
  "id"      : 3,
  "jsonrpc" : "2.0"
}

The close method doesn't return a result with the JSON-RPC 2.0 response, so the field will be null.

{
  "id"      : 3,
  "result"  : null,
  "jsonrpc" : "2.0"
}

The following table is an overview of the Json2Ldap web API. The calls can be grouped into seven categories according to operation type and have a close resemblance of the standard LDAP API.

Directory connection Directory authentication Directory read and search
Directory write operations Extended directory operations Web service information
Directory schema information

1. Directory connection

An LDAP session is started by making an ldap.connect request. To establish a secure LDAP connection over TLS or SSL set the optional request security parameter to the desired protocol.

Json2Ldap also allows clients to connect to a default LDAP server specified in the web.xml configuration file. To request a default connection simply send an ldap.connect request with the server host parameter omitted.

To check whether an LDAP connection is still usable use the ldap.isConnected method.

Once you no longer need an LDAP connection you should close it with ldap.close. Otherwise the connection will be closed automatically by Json2Ldap after an idle period of time.

ldap.connect

Creates a new LDAP server connection.

If the host parameter is omitted Json2Ldap will attempt to make a connection to the default LDAP server (specified by the json2ldap.defaultConnection.* configuration parameters).

To make a secure LDAP connection set the optional security parameter to "StartTLS" or "SSL". Always use secure connections when authenticating via ldap.simpleBind or when dealing with sensitive directory data.

This method also allows an optional simple bind (authentication) to be performed with the same request (requires the bindDN and bindPassword parameters to be set), otherwise the connection is started in anonymous mode. The bind (authentication) operation can also be performed later, after connection is established, with a separate request, or to switch the current user, using ldap.simpleBind or ldap.anonymousBind.

Note that if Json2Ldap is configured to require authentication (see configuration parameter json2ldap.clients.requireAuthentication) a bindDN and a bindPassword parameter must be included with the ldap.connect request, otherwise the connection will be refused.

Parameters:

Result:

ldap.isConnected

Checks if the specified LDAP connection is still active. If the result is false or the response produces an -1000 error "Invalid/expired LDAP connection identifier (CID)" then you will need to start a new connection to continue work.

Parameters:

Result:

ldap.close

Closes the specified LDAP connection. The connection identifier (CID) becomes invalidated.

Parameters:

Result:

2. Authentication

User authentication to a directory is performed using an LDAP "bind" operation. Use the ldap.simpleBind method to request a simple bind with a user DN and password. To make an anonymous bind use the ldap.anonymousBind method. LDAP connections are normally started in anonymous mode, so you don't need to call this method unless you wish to switch the mode of an already authenticated connection back to anonymous.

Note that if Json2Ldap is configured to require authentication (see configuration parameter json2ldap.clients.requireAuthentication) clients will be required to provide a bind DN and password with the initial connection request. Requests for anonymous re-bind will be refused.

Also note that Json2Ldap will refuse to relay bind requests if the configuration parameter json2ldap.clients.denyBindRequests is set.

ldap.simpleBind

Makes a simple bind (authenticate) request for the specified connection, providing a user distinguished name (DN) and password.

Parameters:

Result:

ldap.anonymousBind

Makes an anonymous (authenticate) bind request for the specified connection. Essentially, this is a simple bind with an empty user DN and password. LDAP connections are normally started in anonymous mode, so you won't need to call this method unless you wish to switch the mode of an authenticated connection back to anonymous.

Parameters:

Result:

3. Directory read and search operations

Json2Ldap supports all standard LDAP operations for retrieving and searching directory entries. To obtain the attributes of a specific entry by its DN call the ldap.getEntry method. The ldap.compare method can be used to determine whether an entry contains a given attribute value. To request a directory search use ldap.search. The ldap.getRootDSE method allows clients to retrieve information about the capabilities of the directory server, server vendor and version information, and published naming contexts.

Note that Json2Ldap will refuse to relay read or search requests if the configuration parameter json2clients.clients.denyReadRequests is set.

ldap.getEntry

Retrieves the entry with the specified distinguished name (DN).

Parameters:

Result:

ldap.search

Requests a directory search. For most situations it is sufficient to specify the minimum CID, baseDN, scope and filter parameters. The matching entries may be sorted by one or more attributes using the optional sort parameter. The search result may be alternatively formatted as LDIF.

Parameters:

Result:

ldap.compare

Determines whether the specified entry contains a given attribute value.

Parameters:

Result:

ldap.getRootDSE

Retrieves the directory server root DSE, which provides information about the capabilities of the directory server, server vendor and version information, and published naming contexts.

Parameters:

Result:

4. Directory Write Operations

Json2Ldap supports all standard LDAP operations for updating a directory. To add a new entry to a directory use the ldap.add method. Entry removal is done with a ldap.delete request. To remove a tree of entries with a single request use the powerful ldap.deleteTree method. To update an entry choose one of the ldap.modify variants. Finally, entry renaming and relocation are done with the ldap.modifyDN method.

The ldap.add and ldap.modify methods also have alternative parameter signatures which accept an LDIF record to specify the desired operation.

Note that Json2Ldap will refuse to relay write requests if the json2ldap.clients.denyWriteRequests configuration parameter is set.

ldap.add

Adds a new entry to the directory.

Parameters:

Result:

ldap.add (LDIF)

Adds a new entry to the directory specified as an LDIF string.

Parameters:

Result:

ldap.delete

Deletes the specified directory entry.

Parameters:

Result:

ldap.deleteTree

Deletes the specified directory entry and all its children. Uses a subtree delete request control (OID 1.2.840.113556.1.4.805) which may not be supported by some LDAP servers.

Parameters:

Result:

ldap.modify

Modifies a directory entry.

Parameters:

Result:

ldap.modify (multiple)

Performs multiple modifications of a directory entry.

Parameters:

Result:

ldap.modify (LDIF)

Modifies one or more attributes of a directory entry using the specified LDIF string.

Parameters:

Result:

ldap.modifyDN

Renames and/or moves the specified entry or subtree in the directory.

Parameters:

Result:

5. Extended directory operations

Json2Ldap also provides support for two relatively common extended operations.

For LDAP servers that implement the password modify mechanism (RFC 3062) gateway clients can use the corresponding ldap.ext.passwordModify request.

The ldap.ext.whoAmI request (RFC 4532) allows clients to query their current authorisation identity.

ldap.ext.passwordModify

Makes a password modify extended request as defined in RFC 3062. It may be used to change the password for a user in the directory, and provides the ability to specify the current password for verification. It also offers the ability to request that the server generate a new password for the user.

Note that Json2Ldap will refuse to relay the request if the json2ldap.clients.denyPasswordModifyRequests configuration parameter is set.

Parameters:

Result:

ldap.ext.whoAmI

Makes a "Who am I?" extended request as defined in RFC 4532. It may be used to request the current authorisation identity associated with the client connection.

Note that Json2Ldap will refuse to relay the request if the json2ldap.clients.denyWhoAmIRequests configuration parameter is set.

Parameters:

Result:

6. Directory schema information

Json2Ldap provides a set of requests with the ldap.schema.* prefix that allow clients to query information about the schema of a directory. They can be used to get important details about the object classes as well as the attribute types and their syntaxes and matching rules.

If for some reason a directory server doesn't supply information on its schema a -1600 error "Schema not available" will be returned.

Note that Json2Ldap will refuse to relay a schema request if the json2ldap.clients.denyReadRequests configuration parameter is set.

ldap.schema.getObjectClass

Retrieves the object class with the specified name or OID from the server schema.

Parameters:

Result:

ldap.schema.getObjectClasses

Retrieves the object classes contained in the server schema or optionally just the ones that govern the specified entry.

Parameters:

Result:

ldap.schema.getAttributeType

Retrieves the attribute type with the specified name or OID from the server schema.

Parameters:

Result:

ldap.schema.getAttributeTypes

Retrieves the attribute types contained in the server schema or optionally just the ones that govern the specified entry.

Parameters:

Result:

ldap.schema.getMatchingRule

Retrieves the matching rule with the specified name or OID from the server schema.

Parameters:

Result:

ldap.schema.getMatchingRules

Retrieves the matching rules contained in the server schema or optionally just the ones that govern the specified entry.

Parameters:

Result:

ldap.schema.getMatchingRuleUse

Retrieves the matching rule use with the specified name or OID from the server schema.

Parameters:

Result:

ldap.schema.getMatchingRuleUses

Retrieves the matching rule uses contained in the server schema or optionally just the ones that govern the specified entry.

Parameters:

Result:

ldap.schema.getSyntax

Retrieves the attribute syntax with the specified OID from the server schema.

Parameters:

Result:

ldap.schema.getSyntaxes

Retrieves the attribute syntaxes contained in the server schema or optionally just the ones that govern the specified entry.

Parameters:

Result:

7. Web service information

Apart from the LDAP specific requests, Json2Ldap also provides three methods to obtain information about the gateway web service itself. There are the ws.getName and ws.getVersion methods to identify the software and its version, as well as the ws.getTime method that reports the local time at the web server.

ws.getName

Reports the name of web service software.

Parameters: none

Result:

ws.getVersion

Reports the version of the web service software.

Parameters: none

Result:

ws.getTime

Reports the local web service time in ISO 8601 format yyyy-MM-dd'T'HH:mm:ssZZ, for example "2010-03-31T23:59:59+03:00".

Parameters: none

Result: