Nimbus Directory Services

Json2Ldap Web API

Json2Ldap provides web clients with LDAP directory access by means of JSON-RPC 2.0, the latest version of the simple protocol for remote procedure calls (RPC) using JSON-encoded messages. Requests are received with HTTP POST.

Directory connection » Directory authentication » Directory read and search »
Directory write operations » Extended directory operations » Utility functions »
Directory schema information » SRP-6a authentication »
Web service information »

Web clients start a directory session by requesting Json2Ldap to make a new connection to a specified LDAP server. Json2Ldap then returns a connection identifier (CID) 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 purged automatically by Json2Ldap after an idle period specified by the json2ldap.clients.maxIdleTime configuration parameter.

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

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

If ldap.connect 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"  : { "CID" : "45d0677d-a336-463b-ad99-c82137d03a00" },
  "id"      : 1,
  "jsonrpc" : "2.0"
}

If, however, the connect request fails for some reason, Json2Ldap will return a JSON-RPC 2.0 error response.

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

Sending Json2Ldap requests from browsers is easy, due to the JavaScript nature of JSON-RPC 2.0 messages. Here is an example of making the above ldap.connect call in JavaScript, using the popular jQuery library.

var url = "http://my-web-service.net/json2ldap/";

var request = {};
request.method = "ldap.connect";
request.params = {};
request.params.host = "ldap.example.com";
request.params.port = 389;
request.id = 1;
request.jsonrpc = "2.0";

function callback(response) {

        if (response.result)
                alert("LDAP connection identifier: " + response.result.CID);

        else if (response.error)
                alert("LDAP connect error: " + response.error.message);
};

$.post(url, JSON.stringify(request), callback, "json");

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 for requests that involve directory data, 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 a directory entry with distinguished name (DN) uid=alice,ou=people,dc=wonderland,dc=net:

{
  "method"  : "ldap.getEntry",
  "params"  : { "CID" : "45d0677d-a336-463b-ad99-c82137d03a00",
                "DN"  : "uid=alice,ou=people,dc=wonderland,dc=net" },
  "id"      : 2,
  "jsonrpc" :"2.0"
}

The resulting ldap.getEntry response may look like this:

{
  "result" : { "DN"              : "uid=alice,ou=people,dc=wonderland,dc=net",
               "objectClass"     : [ "top", 
                                     "person", 
                                     "inetorgperson", 
                                     "organizationalperson" ],
               "cn"              : ["Alice Adams"],
               "sn"              : ["Adams"],
               "uid"             : ["alice"],               
               "mail"            : ["alice@wonderland.net"],
               "telephoneNumber" : ["+1 685 622 6202"],
               "employeeNumber"  : ["18001"] },
 "id"      : 1,
 "jsonrpc" : "2.0"
}

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

{
  "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"
}

To access Json2Ldap from browser JavaScript you can use standard XHR calls, either directly or through libraries such as jQuery. The Json2Ldap web service can of course be accessed from other programming languages and environments too.

How to read the API reference

  • The request parameters can be mandatory or optional.
  • The optional request parameters are enclosed in square brackets. If omitted from the request Json2Ldap will take their default value (given after the equals sign).

Note: Json2Ldap accepts only named JSON-RPC 2.0 request parameters (key-value pairs); positional parameters are not accepted. Using named parameters allows RPC methods with multiple optional parameters and makes it possible to introduce additional ones in future without breaking backward API compatibility.

1. Directory connection

An LDAP session is started by making an ldap.connect request. Plain as well as TLS/SSL LDAP connections are supported.

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

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

ldap.connect

Makes a new LDAP directory connection. Returns a connection identifier string (CID) on success to allow the client to reference the open connection in subsequent requests.

If the host parameter is omitted Json2Ldap will attempt to make a connection to the default LDAP server.

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

ldap.connect also allows an optional bind (authentication) to be performed with the same request (see the simpleBind, plainBind, digestMD5Bind and srp6Bind parameters), 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, ldap.anonymousBind, ldap.plainBind, ldap.digestMD5Bind or x.srp6.bind.

Note that if Json2Ldap is configured to require authentication the bind option becomes mandatory, otherwise the connection will be refused. Also, only connections to white-listed LDAP servers are allowed.

Parameters:

Result:

Examples:

Request message to make a connection to the default LDAP server:

{ "method"  : "ldap.connect",
  "id"      : 1, 
  "jsonrpc" : "2.0" }

Example response message on success, returning an LDAP connection identifier (CID) which the client should save in order to refer to the connection is subsequent directory requests:

{ "result"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response message if there is no configured default LDAP server:

{ "error"   : { "message" : "Default connections disabled",
                "code"    : -1122 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to connect to a directory server with StartTLS security:

{ "method"  : "ldap.connect",
  "params"  : { "host"     : "directory.wonderland.net",
                "port"     : 389,
	        "security" : "StartTLS" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message with optional simple bind authentication:

{ "method"  : "ldap.connect",
  "params"  : { "host"       : "directory.wonderland.net",
                "port"       : 389,
	        "security"   : "StartTLS",
		"simpleBind" : { "DN"       : "cn=Directory Manager",
		                 "password" : "secret" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Request message:

{ "method"  : "ldap.isConnected",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

A response message indicating the connection is usable:

{ "result"  : true,
  "id"      : 1,
  "jsonrpc" : "2.0" }

A response error message indicating the connection has expired:

{ "error"   : { "message" : "Invalid/expired LDAP connection identifier (CID)",
                "code"    : -1000 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.close

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

Parameters:

Result:

Examples:

Request message:

{ "method"  : "ldap.close",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message doesn't return a result on success (the field is null):

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

2. Authentication

Users authenticate to a directory with an LDAP "bind" operation.

Use the ldap.simpleBind method to request a simple bind with a user DN and password. This is the most widely supported authentication method by LDAP directories.

The ldap.plainBind call provides additional authentication options. It allows for binding with a username as well as switching the connection to a different user identity (proxied authorisation).

As of version 2.1 Json2Ldap also provides Secure Remote Password (SRP-6a) authentication with the x.srp6.bind call.

To make an anonymous bind use the ldap.anonymousBind method. LDAP connections are normally started in unauthenticated mode, so you don't need to call this method unless you wish an already authenticated connection back to anonymous.

Note that if Json2Ldap is configured to require authentication clients must provide bind details with the initial connection request. Requests for anonymous re-bind will be refused.

Also note that Json2Ldap will refuse user authentication if bind request relay is denied.

ldap.simpleBind

Makes a simple bind (authenticate) request on the specified connection, with the user's distinguished name (DN) and password as credentials.

Parameters:

Result:

Examples:

Request message to authenticate a user for the specified connection (CID):

{ "method"  : "ldap.simpleBind",
  "params"  : { "CID"      : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"       : "uid=alice,ou=people,dc=wonderland,dc=net",
		"password" : "secret" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

On success the reponse message returns an empty JSON object result (it may include various information fields in future versions of Json2Ldap):

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

The response error message if the user DN and/or the password are invalid:

{ "error"   : { "message" : "LDAP error: Invalid credentials",
                "code"    : 49 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.anonymousBind

Makes an anonymous (authenticate) bind request on the specified connection. Essentially, this is a simple bind with an empty user DN and password. LDAP connections are normally started in unauthenticated 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:

Examples:

Example request message to switch the connection to anonymous mode:

{ "method"  : "ldap.anonymousBind",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example success response:

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

ldap.plainBind

Makes a plain SASL bind (authenticate) request on the specified connection. The user identity may be specified either by distinguished name (DN) or by username. Also allows for an optional target authorisation identity to be specified. Requires directory support of PLAIN SASL bind (RFC 4616).

Parameters:

Result:

Examples:

Example request message to authenticate an LDAP connection with the credentials of user "alice":

{ "method"  : "ldap.plainBind",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "username" : "alice",
		"password" : "secret" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to authenticate an LDAP connection with the credentials of user "superuser", but perform all subsequent operations as user "bob":

{ "method"  : "ldap.plainBind",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "username"       : "superuser",
		"targetUsername" : "bob",
		"password"       : "secret" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example success response:

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

ldap.digestMD5Bind

Makes a DIGEST-MD5 SASL bind (authenticate) request on the specified connection. The user identity may be specified either by distinguished name (DN) or by username. Also allows for an optional target authorisation identity to be specified. Requires directory support of DIGEST-MD5 SASL bind (RFC 2831).

Parameters:

Result:

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:

Examples:

Example request message to get all available attributes of DN uid=alice,ou=people,dc=wonderland,dc=net:

{ "method"  : "ldap.getEntry",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"  : "uid=alice,ou=people,dc=wonderland,dc=net" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response message:

{ "result"  : { "DN"           : "uid=alice,ou=people,dc=wonderland,dc=net",
                "objectClass"  : [ "top", 
		                   "person", 
				   "organizationalPerson", 
				   "inetOrgPerson" ],
		"cn"           : [ "Alice Adams" ],
		"sn"           : [ "Adams" ],
		"initials"     : [ "AA" ],
		"mail"         : [ "alice@wonderland.net" ],
		"mobile"       : [ "+1 010 154 3228" ],
		"uid"          : [ "alice" ],
		"userPassword" : [ "c2VjcmV0" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Response error message if the entry could not be retrieved:

{ "error"   : { "message" : "No such entry DN or insufficient permissions",
                "code"    : -1301 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to retrieve only the attributes mail and mobile:

{ "method"  : "ldap.getEntry",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
		"attributes" : ["mail", "mobile"] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "DN"     : "uid=alice,ou=people,dc=wonderland,dc=net",
                "mail"   : [ "alice@wonderland.net" ],
		"mobile" : [ "+1 010 154 3228" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to retrieve only the operational (meta) attributes:

{ "method"  : "ldap.getEntry",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
		"attributes" : "+" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "DN"                    : "uid=alice,ou=people,dc=wonderland,dc=net",
                "entryDN"               : [ "uid=alice,ou=people,dc=wonderland,dc=net" ],
		"entryUUID"             : [ "79a2e891-8e53-35f0-84b4-412108833afd" ],
		"hasSubordinates"       : [ "false" ],
		"numSubordinates"       : [ 0 ],
		"structuralObjectClass" : [ "inetOrgPerson" ],
		"subschemaSubentry"     : [ "cn=schema" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The optional output parameter can be used to request an LDIF result format:

{ "method"  : "ldap.getEntry",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
		"attributes" : ["mail", "mobile"],
		"output"     : "LDIF" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message with LDIF formatted result:

{ "result"  : "dn: uid=alice,ou=people,dc=wonderland,dc=net\n
               mobile: +1 010 154 3228\n
	       mail: alice@wonderland.net\n",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.search

Requests a directory search.

For most situations it is sufficient to specify the minimum CID, baseDN, scope and filter parameters. The optional attributes parameter limits the content of the returned entries.

The matching entries may be sorted by one or more attributes using the optional sort parameter. For this the directory must support the server-side sort control (RFC 2891).

Potentially large result sets may be split into pages by using the optional page parameters. Requires directory support for the simple paged results control (RFC 2696).

The search result may also be alternatively formatted as LDIF by setting the output option accordingly.

Parameters:

Result:

Examples:

Example request message to retrieve all records with a givenName attribute Angelia under the directory branch of ou=people,dc=example,dc=com:

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(givenName=Angelia)" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message, with the attributes of the three found matching records:

{ "result"  : { "matches" : [ { "DN"           : "uid=user.397,ou=people,dc=example,dc=com",
                                "objectClass"  : [ "top", 
		                                   "person", 
				                   "organizationalPerson", 
				                   "inetOrgPerson" ],
		                "cn"           : [ "Angelia Astorino" ],
		                "sn"           : [ "Astorino" ],
				"givenName"    : [ "Angelia" ],
				"mail"         : [ "user.397@maildomain.net" ],
		                "mobile"       : [ "+1 346 488 7815" ],
		                "uid"          : [ "user.111" ] },
				
                               {"DN"           : "uid=user.789,ou=people,dc=example,dc=com",
                                "objectClass"  : [ "top", 
		                                   "person", 
				                   "organizationalPerson", 
				                   "inetOrgPerson" ],
		                "cn"           : [ "Angelia Algood" ],
		                "sn"           : [ "Algood" ],
				"givenName"    : [ "Angelia" ],
				"mail"         : [ "user.789@maildomain.net" ],
		                "mobile"       : [ "+1 415 684 4122" ],
		                "uid"          : [ "user.789" ] },
				
                               {"DN"           : "uid=user.1156,ou=people,dc=example,dc=com",
                                "objectClass"  : [ "top", 
		                                   "person", 
				                   "organizationalPerson", 
				                   "inetOrgPerson" ],
		                "cn"           : [ "Angelia Balduc" ],
		                "sn"           : [ "Balduc" ],
				"givenName"    : [ "Angelia" ],
				"mail"         : [ "user.1156@maildomain.net" ],
		                "mobile"       : [ "+1 057 194 2077" ],
		                "uid"          : [ "user.1156" ] } ],
				
                "referrals" : [] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

An example ldap.search request message which indicates that only the selected attributes mail and mobile should be returned:

{ "method"  : "ldap.search",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN"     : "ou=people,dc=example,dc=com",
		"scope"      : "SUB",
		"filter"     : "(givenName=Angelia)",
		"attributes" : [ "mail", "mobile" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The resulting response message:

{ "result"  : { "matches" : [ { "DN"     : "uid=user.397,ou=people,dc=example,dc=com",
                                "mail"   : [ "user.397@maildomain.net" ],
		                "mobile" : [ "+1 346 488 7815" ] },
				
                              { "DN"     : "uid=user.789,ou=people,dc=example,dc=com",
                                "mail"   : [ "user.789@maildomain.net" ],
		                "mobile" : [ "+1 415 684 4122" ] },
				
                              { "DN"     : "uid=user.1156,ou=people,dc=example,dc=com",
                                "mail"   : [ "user.1156@maildomain.net" ],
		                "mobile" : [ "+1 057 194 2077" ] } ],
				
                "referrals" : [] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message indicating all user entries should be sorted by surname and then by given name (provided the directory supports the server-side sorting control (RFC 2891):

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(objectClass=person)",
		"sort"   : [ { "key" : "sn" },
		             { "key" : "givenName" } ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

And here is a search requesting reverse-ordered sorting:

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(objectClass=person)",
		"sort"   : [ { "key"          : "sn",
		               "reverseOrder" : true },
		             { "key"          : "givenName",
			       "reverseOrder" : true } ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message indicating the matches should be split into pages of size 50. Requires directory support of the simple paged results control (RFC 2696).

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(objectClass=person)",
		"page"   : { "size" : 50 } },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to retrieve the next results page. The page.cookie parameter, whose value was copied from the previous paged result, is used by the directory to determine where to resume the matches retrieval. The string is typically an arbitrary BASE-64 encoded value which is simply passed back to the server. If the directory returns an empty page cookie this means that this was the last page.

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(objectClass=person)",
		"page"   : { "size"   : 50,
		             "cookie" : "AAAAAAAAABw=" } },
  "id"      : 1,
  "jsonrpc" : "2.0" }

As with ldap.getEntry, the matching entries can also be requested as LDIF:

{ "method"  : "ldap.search",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN" : "ou=people,dc=example,dc=com",
		"scope"  : "SUB",
		"filter" : "(givenName=Ang*)",
		"output" : "LDIF" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response, with result output as LDIF:

{ "result"  : { "matches"  : "dn: uid=user.407,ou=people,dc=example,dc=com\n
                     	      objectClass: top\n
                     	      objectClass: person\n
	             	      objectClass: organizationalperson\n
	             	      objectClass: inetorgperson\n
	             	      cn: Angelo Atoui\n
	             	      sn: Atoui\n
	             	      givenName: Angelo\n
	             	      initials: AFA\n
	             	      mail: user.407@maildomain.net\n
	             	      mobile: +1 303 778 2715\n
	             	      uid: user.407\n
	             	      userPassword: {SSHA}JcTSbx+hQlxFIgP0m2FbWOiu7GTqMr4NCSbo6Q==\n
	             	      \n
	             	      dn: uid=user.394,ou=people,dc=example,dc=com\n
                     	      objectClass: top\n
                     	      objectClass: person\n
	             	      objectClass: organizationalperson\n
	             	      objectClass: inetorgperson\n
	             	      cn: Angela Astley\n
	             	      sn: Astley\n
	             	      givenName: Angela\n
	             	      initials: ASA\n
	             	      mail: user.394@maildomain.net\n
	             	      mobile: +1 009 999 0130\n
	             	      uid: user.394\n
	             	      userPassword: {SSHA}vDwfhn8mrLnCKlp4GJxGmuzKZxHsQBPqAhMypQ==\n",
                "referrals" : [] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.compare

Determines whether the specified entry contains a given attribute value.

Parameters:

Result:

Examples:

Example request message, to test whether the entry uid=user.407,ou=People,dc=example,dc=com has a givenName attribute set to Angelo:

{ "method"  : "ldap.compare",
  "params"  : { "CID"       : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"        : "uid=user.407,ou=People,dc=example,dc=com",
		"attribute" : "givenName",
		"value"     : "Angelo" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response indicating a matching attribute value:

{ "result"  : true,
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response indicating no matching attribute value was found:

{ "result"  : false,
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message to get the root DSE of the directory server:

{ "method"  : "ldap.getRootDSE",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response indicating an LDAP v2 + v3 compatible Open DS server, version 2.2.0:

{ "result"  : { "objectClass"                  : [ "top",
		                                   "ds-root-dse" ],
                "firstChangeNumber"            : [ "0" ],
                "lastChangeNumber"             : [ "0" ],
                "changelog"                    : [ "cn=changelog" ],
                "ds-private-naming-contexts"   : [ "cn=admin data",
		                                   "cn=ads-truststore",
						   "cn=backups",
						   "cn=config",
						   "cn=monitor",
						   "cn=schema",
						   "cn=tasks"],
                "entryDN"                      : [ "" ],
                "entryUUID"                    : [ "d41d8cd9-8f00-3204-a980-0998ecf8427e" ],
                "hasSubordinates"              : [ "true" ],
                "namingContexts"               : [ "dc=example,dc=com" ],
                "numSubordinates"              : ["1"],
                "structuralObjectClass"        : [ "ds-root-dse" ],
                "subschemaSubentry"            : [ "cn=schema" ],
                "supportedAuthPasswordSchemes" : [ "MD5",
		                                   "SHA1",
						   "SHA256",
						   "SHA512",
						   "SHA384" ],
                "supportedControl"             : [ "1.2.826.0.1.3344810.2.3",
		                   	 	   "1.2.840.113556.1.4.319",
				   	 	   "1.2.840.113556.1.4.473",
				   	 	   "1.2.840.113556.1.4.805",
				   	 	   "1.3.6.1.1.12",
				   	 	   "1.3.6.1.1.13.1",
				   	 	   "1.3.6.1.1.13.2",
				   	 	   "1.3.6.1.4.1.26027.1.5.2",
				   	 	   "1.3.6.1.4.1.42.2.27.8.5.1",
				   	 	   "1.3.6.1.4.1.42.2.27.9.5.2",
				   	 	   "1.3.6.1.4.1.42.2.27.9.5.8",
				   	 	   "1.3.6.1.4.1.4203.1.10.2",
				   	 	   "1.3.6.1.4.1.7628.5.101.1",
				   	 	   "2.16.840.1.113730.3.4.12",
				   	 	   "2.16.840.1.113730.3.4.16",
				   	 	   "2.16.840.1.113730.3.4.17",
				   	 	   "2.16.840.1.113730.3.4.18",
				   	 	   "2.16.840.1.113730.3.4.19",
				   	 	   "2.16.840.1.113730.3.4.2",
				   	 	   "2.16.840.1.113730.3.4.3",
				   	 	   "2.16.840.1.113730.3.4.4",
				   	 	   "2.16.840.1.113730.3.4.5",
				   	 	   "2.16.840.1.113730.3.4.9" ],
               "supportedExtension"            : [ "1.3.6.1.1.8","1.3.6.1.4.1.26027.1.6.1",
	                                           "1.3.6.1.4.1.26027.1.6.2",
						   "1.3.6.1.4.1.26027.1.6.3",
						   "1.3.6.1.4.1.4203.1.11.1",
						   "1.3.6.1.4.1.4203.1.11.3",
						   "1.3.6.1.4.1.1466.20037" ],
               "supportedFeatures"             : [ "1.3.6.1.1.14",
	                                           "1.3.6.1.4.1.4203.1.5.1",
						   "1.3.6.1.4.1.4203.1.5.2",
						   "1.3.6.1.4.1.4203.1.5.3" ],
               "supportedLDAPVersion"          : [ "2",
	                                           "3" ],
               "supportedSASLMechanisms"       : [ "PLAIN",
	                                           "EXTERNAL",
						   "DIGEST-MD5",
						   "CRAM-MD5" ],
                "vendorName"                   : [ "Sun Microsystems, Inc." ],
		"vendorVersion"                : [ "OpenDS Directory Server 2.2.0" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message to add a new user with distinguished name (DN) uid=alice,ou=people,dc=example,dc=com:

{ "method"  : "ldap.add",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"         : "uid=alice,ou=people,dc=example,dc=com",
		"attributes" : { "objectClass" : [ "top",
		                                   "person",
						   "organizationalPerson",
						   "inetOrgPerson" ],
				 "cn"          : "Alice Wonderland",
				 "sn"          : "Wonderland",
				 "uid"         : "alice" } },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Response error message if a mandatory attribute is missing from the new entry specification:

{ "error"   : { "message" : "LDAP error: Object class violation",
                "code"    : 65 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.add (LDIF)

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

Parameters:

Result:

Examples:

Example request message to add a new user with the specified LDIF record:

{ "method"  : "ldap.add",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "LDIF" : "dn: "uid=user.9999,ou=people,dc=example,dc=com\n
		          objectClass: top\n
			  objectClass: person\n
			  objectClass: organizationalPerson\n
			  objectClass: inetOrgPerson\n
			  cn: Alice Wonderland\n
			  sn: Wonderland\n
			  uid: user.9999\n" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.delete

Deletes the specified directory entry.

Parameters:

Result:

Examples:

Example request message to delete the entry with DN uid=user.9999,ou=people,dc=example,dc=com:

{ "method"  : "ldap.delete",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"  : "uid=user.9999,ou=people,dc=example,dc=com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response message on success:

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

Example error response indicating an invalid DN:

{ "error"   : { "message" : "LDAP error: No such object",
                "code"    : 32 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message to delete the directory branch ou=accounting,dc=example,dc=com:

{ "method"  : "ldap.deleteTree",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"  : "ou=accounting,dc=example,dc=com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.modify

Modifies a directory entry.

Parameters:

Result:

Examples:

Example request message to add two new attribute values:

{ "method"  : "ldap.modify",
  "params"  : { "CID"       : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"        : "uid=user.9999,ou=people,dc=example,dc=com",
		"attribute" : "mail",
		"type"      : "ADD",
		"values"    : [ "alice@wonderland.com", "alice@example.com" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to delete an attribute value:

{ "method"  : "ldap.modify",
  "params"  : { "CID"       : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"        : "uid=user.9999,ou=people,dc=example,dc=com",
		"attribute" : "mail",
		"type"      : "DELETE",
		"values"    : [ "alice@example.com" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request message to replace an attribute value:

{ "method"  : "ldap.modify",
  "params"  : { "CID"       : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"        : "uid=user.9999,ou=people,dc=example,dc=com",
		"attribute" : "mail",
		"type"      : "REPLACE",
		"values"    : [ "alice@myland.com" ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.modify (multiple)

Performs multiple modifications of a directory entry.

Parameters:

Result:

Examples:

Example request message to add two new attributes telephoneNumber and mobile:

{ "method"  : "ldap.modify",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"   : "uid=user.9999,ou=people,dc=example,dc=com",
		"mods" : [ { "attribute" : "telephoneNumber",
		             "type"      : "ADD",
			     "values"    : [ "+1 354 2344 5433" ] },
			   { "attribute" : "mobile",
			     "type"      : "ADD",
			     "values"    : [ "+1 123 4544 1290" ] } ] },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.modify (LDIF)

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

Parameters:

Result:

Examples:

Example request message to add two new attribute values:

{ "method"  : "ldap.modify",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "LDIF" : "dn: uid=user.9999,ou=people,dc=example,dc=com\n
		          changetype: modify\n
			  add: mail\n
			  mail: alice@wonderland.com\n
			  mail: alice@example.com\n" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.modifyDN

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

Parameters:

Result:

Examples:

Example request to change the RDN of an entry from uid=user.9999 to cn=Alice Wonderland:

{ "method"  : "ldap.modifyDN",
  "params"  : { "CID"    : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"     : "uid=user.9999,ou=people,dc=example,dc=com",
		"newRDN" : "cn=Alice Wonderland" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request to move an entry to a different directory branch while preserving its RDN:

{ "method"  : "ldap.modifyDN",
  "params"  : { "CID"           : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "DN"            : "uid=user.9999,ou=people,dc=example,dc=com",
		"newRDN"        : "uid=user.9999",
		"newSuperiorDN" : "ou=accounting,dc=example,dc=com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

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) Json2Ldap clients can use the corresponding ldap.ext.passwordModify request.

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

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:

Examples:

Example request to modify the password of the currently authenticated user from secret to s3cr3t:

{ "method"  : "ldap.ext.passwordModify",
  "params"  : { "CID"         : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "oldPassword" : "secret",
		"newPassword" : "s3cr3t" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The corresponding response message on successful password change:

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

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:

Examples:

Example request message:

{ "method"  : "ldap.ext.whoAmI",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response message:

{ "result"  : "dn:uid=user.0,ou=People,dc=example,dc=com",
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message to get the schema of the person object class:

{ "method"  : "ldap.schema.getObjectClass",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "name" : "person" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "OID"                : "2.5.6.6",
                "names"              : [ "person" ],
		"description"        : null,
		"obsolete"           : false,
		"type"               : "STRUCTURAL",
		"requiredAttributes" : [ "sn",
		                         "cn" ],
                "optionalAttributes" : [ "userPassword",
                                         "telephoneNumber",
					 "seeAlso",
					 "description" ],
		"superClasses"       : [ "top" ],
		"rawDefinition"      : "( 2.5.6.6 
		                          NAME 'person' 
		                          SUP top 
					  STRUCTURAL 
					  MUST ( sn $ cn ) 
					  MAY ( userPassword $ 
					        telephoneNumber $ 
						seeAlso $ 
						description ) 
					  X-ORIGIN 'RFC 4519' )" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getObjectClasses

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getObjectClasses",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getAttributeType

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getAttributeType",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "name" : "mail" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "OID"            : "0.9.2342.19200300.100.1.3",
                "names"          : [ "mail", "rfc822Mailbox" ],
		"description"    : null,
		"usage"          : "userApplications",
		"obsolete"       : false,
		"singleValued"   : false,
		"readOnly"       : false,
		"collective"     : false,
		"syntaxOID"      : "1.3.6.1.4.1.1466.115.121.1.26{256}",
		"equalityMatch"  : "caseIgnoreIA5Match",
		"orderingMatch"  : null,
		"substringMatch" : "caseIgnoreIA5SubstringsMatch",
		"superType"      : null,
		"rawDefinition"  : "( 0.9.2342.19200300.100.1.3 
		                      NAME ( 'mail' 'rfc822Mailbox' ) 
				      EQUALITY caseIgnoreIA5Match 
				      SUBSTR caseIgnoreIA5SubstringsMatch 
				      SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} 
				      X-ORIGIN 'RFC 4524' )" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getAttributeTypes

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getAttributeTypes",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getMatchingRule

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getMatchingRule",
  "params"  : { "CID"  : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "name" : "en-US" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "OID"           : "0.9.2342.19200300.100.1.3",
                "names"         : [ "en", "en-US" ],
		"description"   : null,
		"obsolete"      : false,
		"syntaxOID"     : "1.3.6.1.4.1.1466.115.121.1.15",
		"rawDefinition" : "( 1.3.6.1.4.1.42.2.27.9.4.34.1 
		                     NAME ( 'en' 'en-US' ) 
				     SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getMatchingRules

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getMatchingRules",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message:

{ "method"  : "ldap.schema.getSyntax",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "OID" : "1.3.6.1.4.1.1466.115.121.1.7" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : { "OID"           : "1.3.6.1.4.1.1466.115.121.1.7",
                "description"   : "Boolean",
		"rawDefinition" : "( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' )" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.schema.getSyntaxes

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

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.schema.getSyntaxes",
  "params"  : { "CID" : "15002fb7-a830-413f-9445-858cf9a2cc6d" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

7. Utility functions

Json2Ldap provides a set of LDAP utility requests for processing distinguished names (DNs) and search filter values. These requests do not require a directory connection (CID) in order to be used.

ldap.util.isValidDN

Indicates whether the provided string represents a valid distinguished name (DN).

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.util.isValidDN",
  "params"  : { "DN" : "cn=Alice Wonderland,ou=people,dc=example,dc=com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : true,
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.util.normalizeDN

Retrieves a normalized representation of the specified distinguished name (DN).

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.util.normalizeDN",
  "params"  : { "DN" : "CN = Alice Wonderland, OU = people, DC = example, DC = com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "cn=alice wonderland,ou=people,dc=example,dc=com",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.util.compareDNs

Compares the provided DN values to determine their relative order in a sorted list.

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.util.compareDNs",
  "params"  : { "DN1" : "cn=Alice",
                "DN2" : "cn=Bob" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : -1,
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.util.isValidFilter

Tests if the specified string represents a valid LDAP search filter.

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.util.isValidFilter",
  "params"  : { "filter" : "&(objectClass=person)(givenName=Alice)" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : true,
  "id"      : 1,
  "jsonrpc" : "2.0" }

ldap.util.encodeFilterValue

Encodes the provided string into a form suitable for use as the assertion value in a search filter. Parentheses, asterisks, backslashes, null characters, and any non-ASCII characters will be escaped using a backslash before the hexadecimal representation of each byte in the character to escape.

Parameters:

Result:

Examples:

Example request message:

{ "method"  : "ldap.util.encodeFilterValue",
  "params"  : { "value" : "a*b*c" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "a\2ab\2ac",
  "id"      : 1,
  "jsonrpc" : "2.0" }

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.

Authenticating clients must use the SRP crypto parameters and routines as advertised by x.srp6.getSettings. The authentication process itself has two steps, see x.srp6.bind (step 1) and x.srp6.bind (step 2). Json2Ldap also provides a convenience method for setting user SRP-6a credentials with x.srp6.setVerifier.

x.srp6.getSettings

Gets the public Secure Remote Password (SRP-6a) authentication settings. These must used by all authenticating clients, else SRP-6a authentication will fail with a false Bad SRP-6a authentication credentials error.

If SRP-6a authentication is disabled the response will be an SRP-6a authentication disabled error.

Parameters: none

Result:

Example request to get the Json2Ldap SRP-6a settings:

{ "method"  : "x.srp6.getSettings",
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response detailing the crypto parameters, the preferred salt byte size and explanation of the 'x', 'M1' and 'M2' routines:

{ "result"  : { "N"        : "115b8b692e0e045692cf280b436735c77a5a9e8a9e7ed56c965f87db5b2a2ece3",
                "g"        : "2",
	        "H"        : "SHA-1",
	        "saltSize" : 16,
	        "x"        : "H(s|H(P))",
	        "M1"       : "H(A|B|S)",
	        "M2"       : "H(A|M1|S)" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

x.srp6.bind (step 1)

Performs the first step of a Secure Remote Password (SRP-6a) authentication. After completing step 1 the client should proceed to step 2.

Note that Json2Ldap will not tell if the authenticating user identity is invalid or non-existing; instead, this will be indicated as an unspecified Bad SRP-6a authentication credentials error at step two.

Parameters:

Result:

Example SRP-6a step one authentication request for user with DN uid=bob,ou=people,dc=wonderland,dc=net:

{ "method"  : "x.srp6.bind",
  "params"  : { "CID" : "c5b871ad-1f9c-448b-a66b-6d54654f42b7",
                "DN"  : "uid=bob,ou=people,dc=wonderland,dc=net" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The user identity may be alternatively specified as a username provided the LDAP directory is able to resolve it to a valid user DN:

{ "method"  : "x.srp6.bind",
  "params"  : { "CID"      : "c5b871ad-1f9c-448b-a66b-6d54654f42b7",
                "username" : "bob" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response containing the public SRP-6a crypto parameters (prime 'N', generator 'g' and hash algorithm 'H'), the user password salt 's' and the public server value 'B' computed from the user password verifier:

{ "result"  : { "N" : "115b8b692e0e045692cf280b436735c77a5a9e8a9e7ed56c965f87db5b2a2ece3",
                "g" : "2",
	        "H" : "SHA-1",
		"B" : "daad028c1e69bf427473c89970bcf11083b6c0460833ae87e2303bfd00cec73f",
	        "s" : "b24c9bc199aafd143a94" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

x.srp6.bind (step 2)

Performs the second step of a Secure Remote Password (SRP-6a) authentication. Step two must be called within a limited amount of time after step one else Json2Ldap will return a SRP-6a session timeout error.

Json2Ldap will return a Bad SRP-6a authentication credentials error if the user identity or the password provided to the client at the start of the authenticating session were invalid.

Parameters:

Result:

Example SRP-6a step two authentication request:

{ "method"  : "x.srp6.bind",
  "params"  : { "CID" : "c5b871ad-1f9c-448b-a66b-6d54654f42b7",
                "A"   : "1154a0b91391993aa40aeb07d27da5363231029c257a8ba03127e65910516b665" },
		"M1"  : "ee3a8d184bb148cb35852fd726f9dec1c866257f" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response indicating the user was successfully authenticated. The client may use the evidence message 'M2' to validate the server identity (for mutual authentication).

{ "result"  : { "M2" : "40fd71cc3ee0224678447f1c11b8327577f365f7" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Json2Ldap will return a Bad SRP-6a authentication credentials error if the user identity or the password provided to the client at the start of the authenticating session were invalid:

{ "error"   : { "message" : "Bad SRP-6a authentication credentials",
                "code"    : -1714 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

x.srp6.setVerifier

Sets a user's salt s' and verifier 'v' for Secure Remote Password (SRP-6a) authentication. The caller must have write access to the SRP-6a credentials attribute (their own or of the target user if a different user DN is specified).

The salt s and the verifier v must be generated by the client using the SRP-6a crypto parameters advertised by x.srp6.getSettings else all subsequent x.srp6.bind requests for the user will falsely fail.

Parameters:

Result:

Example request to set a new salt 's' and verifier 'v' for the current user:

{ "method"  : "x.srp6.setVerifier",
  "params"  : { "CID" : "c5b871ad-1f9c-448b-a66b-6d54654f42b7",
                "s"   : "b24c9bc199aafd143a94" },
		"v"   : "10b3a3986ec57075d1a8f83bafc3350f582f6bd08064d3a09b9f5b4cdcf21c6ee" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request to set a new salt 's' and verifier 'v' for another user (the caller must have write access to their SRP-6a credentials attribute):

{ "method"  : "x.srp6.setVerifier",
  "params"  : { "CID" : "c5b871ad-1f9c-448b-a66b-6d54654f42b7",
                "DN"  : "uid=alice,ou=people,dc=wonderland,dc=net",
                "s"   : "b24c9bc199aafd143a94" },
		"v"   : "10b3a3986ec57075d1a8f83bafc3350f582f6bd08064d3a09b9f5b4cdcf21c6ee" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

8. Web service information

Apart from the LDAP specific requests, Json2Ldap also provides three methods to obtain information about the web service itself. There are the ws.getName and ws.getVersion methods to identify the service 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:

Examples:

Example request message:

{ "method"  : "ws.getName",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "Json2Ldap",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ws.getVersion

Reports the version of the web service software.

Parameters: none

Result:

Examples:

Example request message:

{ "method"  : "ws.getVersion",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "2.1 (2011-12-06)",
  "id"      : 1,
  "jsonrpc" : "2.0" }

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:

Examples:

Example request message:

{ "method"  : "ws.getTime",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "2010-11-15T12:14:41+02:00",
  "id"      : 1,
  "jsonrpc" : "2.0" }