Web API

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

Overview of the Json2Ldap web API:

Web clients begin a directory session by requesting Json2Ldap to make a new connection to a specified LDAP server. Json2Ldap then returns a connection identifier (CID), or handler, 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 to establish a plain connection to an LDAP server on host ldap.example.com that listens on port 389. The host can alternatively be specified by its IP address.

{
  "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 the ldap.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 the 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 can’t find out which LDAP connection the client is referring to.

Here is an example ldap.getEntry request 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 an 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 as well.

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.

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 send an 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.

Connections that are no longer in use should be closed, otherwise the client may end up exhausting their connection quote per IP address or authenticated user, which will be indicated by an error, such as a -1200 “Exhausted connection quota for this user” on ldap.connect.

Parameters:

• [ host = null ] {string} The host name or IP address of the LDAP server. If omitted or set to null Json2Ldap will attempt to make a connection to the default LDAP server, overriding any port, timeout and security parameters set here.

• [ port = 389 ] {integer} The port number of the LDAP server. It should be a value between 1 and 65535, inclusive. LDAP servers are typically assigned port 389 for plain and StartTLS connections and port 636 for SSL connections.

• [ timeout = 0 ] {integer} The maximum length of time in milliseconds to wait for the connection to be established before failing, or zero to indicate that no timeout should be enforced (although if the attempt stalls long enough, then the underlying operating system may cause it to timeout).

• [ security = “none” ] {“none”|“StartTLS”|“SSL”} Specifies the connection security:

  • “none” for a plain unencrypted connection (default).

  • “StartTLS” for a secure connection using a StartTLS extended operation.

  • “SSL” for a secure connection over SSL.

• [ trustSelfSignedCerts = false ] {true|false} Determines whether to accept self-signed certificates presented by the LDAP server (applies to secure “StartTLS” and “SSL” connections only).

• [ simpleBind = null ] {object} If specified authenticates the new LDAP connection by means of a simple bind with a user DN and password. Object members:

  • DN {string} The user distinguished name (DN).

  • password {string} The user password.

  • [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ plainBind = null ] {object} If specified authenticates the new LDAP connection by means of a PLAIN SASL bind with a DN or username and a password. Also allows for an optional target authorisation identity to be specified. Requires directory support of PLAIN SASL bind (RFC 4616). Object members:

  • DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the directory must be able to resolve it to a unique directory entry.

  • [ targetDN | targetUsername = null ] {string} Allows an optional target authorisation identity to be specified, either by distinguished name (DN) or by username. Use this option to authenticate as one (super)user, but perform all subsequent operations as another.

  • password {string} The password of the authenticating user.

  • [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ digestMD5Bind = null ] {object} If specified authenticates the new LDAP connection by means of a DIGEST-MD5 SASL bind with a DN or username and a password. Also allows for an optional target authorisation identity to be specified. Requires directory support of DIGEST-MD5 SASL bind (RFC 2831). Object members:

  • DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the directory must be able to resolve it to a unique directory entry.

  • [ targetDN | targetUsername = null ] {string} Allows an optional target authorisation identity to be specified, either by distinguished name (DN) or by username. Use this option to authenticate as one (super)user, but perform all subsequent operations as another.

  • password {string} The password of the authenticating user.

  • [ realm = null ] {string} If specified the realm into which the user should authenticate.

  • [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ srp6Bind = null ] {object} If specified begins authentication of the new LDAP connection using the Secure Remote Password (SRP-6a) protocol. To complete SRP-6a authentication the client must then proceed to x.srp6.bind (step 2). Object members:

  • DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the LDAP directory must be able to resolve it to a unique directory entry (by means of a plain SASL bind with username authzId).

  • [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the step 2 response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties (of these only CID is always included, the rest are optional):

• “CID” {string} The connection identifier (CID) representing the new LDAP connection. Use it to refer to the connection in subsequent requests.

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter. The value will be null if the authzId was requested but the control is not supported by the directory server.

• “N” {string} The safe prime ‘N’, in hexadecimal encoding, if SRP-6a authentication was requested.

• “g” {string} The generator ‘g’ parameter, in hexadecimal encoding, if SRP-6a authentication was requested.

• “H” {string} The hash algorithm ‘H’, if SRP-6a authentication was requested.

• “B” {string} The public server value ‘B’, in hexadecimal encoding, , if SRP-6a authentication was requested.

• “s” {string} The password salt ‘s’, in hexadecimal encoding, if SRP-6a authentication was requested.

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 in 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 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 to connect to a directory server with SSL security on the standard port (636) and accept certificates which are self-signed or not issued by a recognised Certificate Authority (CA).

{ "method"  : "ldap.connect",
  "params"  : { "host"                 : "directory.wonderland.net",
                "port"                 : 636,
                "security"             : "SSL",
                "trustSelfSignedCerts" : true },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example request 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:

• CID {string} The connection identifier (CID).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{true|false} Boolean true if the connection is active, otherwise false.

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.

Connections that are no longer in use should be closed, otherwise the client may end up exhausting their connection quote per IP address or authenticated user, which will be indicated by an error, such as a -1200 “Exhausted connection quota for this user” on ldap.connect.

Parameters:

• CID {string} The connection identifier (CID) representing the connection.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Request message:

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

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

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

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:

• CID {string} The connection identifier (CID).

• DN {string} The user distinguished name (DN).

• password {string} The user bind password.

• [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object on success with the following optional properties:

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter. The value will be null if the authzId was requested but the control is not supported by the directory server.

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 response 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:

• CID {string} The connection identifier (CID).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object on success with the following optional properties:

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter. The value will be null if the authzId was requested but the control is not supported by the directory server.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the directory must be able to resolve it to a unique directory entry.

• [ targetDN | targetUsername = null ] {string} Allows an optional target authorisation identity to be specified, either by distinguished name (DN) or by username. Use this option to authenticate as one (super)user, but perform all subsequent operations as another.

• password {string} The password of the authenticating user.

• [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object on success with the following optional properties:

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter. The value will be null if the authzId was requested but the control is not supported by the directory server.

Examples:

Example request 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 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:

• CID {string} The connection identifier (CID).

• DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the directory must be able to resolve it to a unique directory entry.

• [ targetDN | targetUsername = null ] {string} Allows an optional target authorisation identity to be specified, either by distinguished name (DN) or by username. Use this option to authenticate as one (super)user, but perform all subsequent operations as another.

• password {string} The password of the authenticating user.

• [ realm = null ] {string} If specified the realm into which the user should authenticate.

• [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object on success with the following optional properties:

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter. The value will be null if the authzId was requested but the control is not supported by the directory server.

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

All user attributes of the entry will be retrieved (as UTF-8 strings) unless an explicit list is provided with the attributes parameter. Use the binaryAttributes parameter if you want to retrieve binary data as BASE64-encoded strings.

The entry can be alternatively returned as LDIF by setting the optional output parameter accordingly.

Parameters:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the entry to retrieve.

• [ attributes = “*” ] {array|string} The set of attributes to retrieve (as UTF-8 text), specified as an array of strings or as a string containing the attribute names separated by space or commas. If omitted or set to “*” all attributes will be requested. If set to “+” the operational attributes will be requested. If empty or set to “1.1” no attributes will be requested.

• [ binaryAttributes = [ ] ] {array|string} The set of attributes to retrieve as BASE64-encoded strings (typically for binary data), specified as an array of strings or as a string containing the attribute names separated by space or commas. If omitted only the above attributes parameter will apply.

• [ normalize = false ] {true|false} The default mode is to return the attribute names in the letter case specified in their directory schema definition. If true the attribute names will be returned in lower case.

• [ output = “JSON” ] {“JSON”|“LDIF”} Specifies the output format, which can be JSON (default) or LDIF.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{ object | string | null } A JSON object containing the entry DN and its attributes as attribute name/value array pairs. If the alternative output format was chosen, the result will be an LDIF string. If the entry doesn’t exist or access to it was denied due to insufficient permissions the result will be null.

Examples:

Example request 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:

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

The response will have a null result if there is no such entry DN or the caller has insufficient permissions:

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

Example request 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:

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

{ "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 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. To simplify retrieval of attributes in client-side code the optional normalize parameter can be used; it ensures all attribute names are returned in lower case.

The matching entries may be sorted by one or more attributes with the optional sort parameter. This requires directory support of the server-side sort control (RFC 2891).

Potentially large result sets may be split into pages with help of the optional page parameter. Requires directory support of the simple-paged-results control (RFC 2696).

The vlv parameter provides an alternative method to subset large result sets. It is more flexible as it enables retrieval of arbitrarily offset and sized result segments. It must be used together with server-side sorting and requires directory support of the virtual-list-view (VLV) control (draft-ietf-ldapext-ldapv3-vlv-09).

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

Parameters:

• CID {string} The connection identifier (CID).

• baseDN {string} The base distinguished name (DN) for the search request.

• scope {“BASE”|“ONE”|“SUB”|“SUBORDINATES”} The scope that specifies the range of entries that should be examined for the search:

  • “BASE” Indicates that only the entry specified by the base DN should be considered.

  • “ONE” Indicates that only entries that are immediate subordinates of the entry specified by the base DN (but not the base entry itself) should be considered.

  • “SUB” Indicates that the base entry itself and any subordinate entries (to any depth) should be considered.

  • “SUBORDINATES” Indicates that any subordinate entries (to any depth) below the entry specified by the base DN should be considered, but not the base entry itself. Requires LDAP server support of the subordinate subtree scope extension (not supported by MS Active Directory).

• filter {string} The filter to use to identify matching entries.

• [ attributes = “*” ] {array|string} The set of attributes to retrieve (as UTF-8 text), specified as an array of strings or as a string containing the attribute names separated by space or commas. If omitted or set to “*” all attributes will be requested. If set to “+” the operational attributes will be requested. If empty or set to “1.1” no attributes will be requested.

• [ binaryAttributes = [ ] ] {array|string} The set of attributes to retrieve as BASE64-encoded strings (typically for binary data), specified as an array of strings or as a string containing the attribute names separated by space or commas. If omitted only the above attributes parameter will apply.

• [ normalize = false ] {true|false} The default mode is to return the attribute names in the letter case specified in their directory schema definition. If true the attribute names will be returned in lower case.

• [ sort = [] ] {array} Allows for optional sorting of the matching entries. Requires directory support of the Server-Side Sort control (RFC 2891). To request a sort by one or more attributes specify an array including the corresponding number of sort key specification objects, each with the following properties:

  • key {string} The name of the attribute for which sorting is to be performed.

  • [ reverseOrder = false ] {true|false} Indicates whether the results should be sorted in ascending or descending order, defaults to false if omitted.

  • [ orderingRule = null ] {string} The name or OID of the ordering matching rule that should be used to perform the sort. If omitted or null the default ordering matching rule for the specified attribute will be used.

• [ page = null ] {object} Allows for optional paging of the returned matches. Requires directory support of the Simple Paged Results control (RFC 2696). To request paging of the results set this parameter to a JSON object with the following properties:

  • size {integer} The desired page size, must be greated than zero.

  • [ cookie = null ] {string} Used to resume the result set retrieval by setting it to the cookie value returned by the previous paged search (see ldap.search result description).

• [ vlv = null] {object} Allows for optional segmenting of the returned matches. Requires directory support of the Virtual List View control (draft-ietf-ldapext-ldapv3-vlv-09). This option can only be used together with the server-side sort control. To request a segment of the results set this parameter to a JSON object with the following properties:

  • [ offset = 1 ] {integer} The position (one-based) of the target entry to return. Defaults to 1 (the first entry).

  • [ before = 0 ] {integer} The number of entries before the target entry offset to return. Defaults to 0 (none).

  • after {integer} The number of entries after the target entry offset to return.

  • [ totalEntryCount = 0 ] {integer} The estimated total number of entries in the complete result set. Should be 0 for the first request in a VLV search sequence, thereafter the totalEntryCount returned by the server in the corresponding VLV result (see ldap.search result description).

  • [ cookie = null ] {string} Used to resume the result set retrieval by setting it to the cookie value returned by the previous VLV search (see ldap.search result description).

• [ derefPolicy = “NEVER” ] {“NEVER”|“SEARCHING”|“FINDING”|“ALWAYS”} The dereference policy the server should use for any aliases encountered while processing the search:

  • “NEVER” Indicates that the server should not dereference any aliases that it encounters.

  • “SEARCHING” Indicates that the server should dereference any aliases that it may encounter while examining candidate entries, but it should not dereference the base entry if it happens to be an alias entry.

  • “FINDING” Indicates that the server should dereference the base entry if it happens to be an alias entry, but it should not dereference any alias entries that may be encountered while examining candidate entries.

  • **“ALWAYS”**s Indicates that the server should dereference the base entry if it happens to be an alias entry, and should also dereference any entries that may be encountered while examining candidates.

• [ sizeLimit = 0 ] {integer} The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit. Note that the LDAP server may impose a stricter overriding limit. If exceeded, the search request will return an “LDAP error: Size limit exceeded” (code 4), discarding any partially retrieved results.

• [ timeLimit = 0 ] {integer} The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit. Note that the LDAP server may impose a stricter overriding limit. If, exceeded the search requests will return an “LDAP error: Time limit exceeded” (code 3), discarding any partially retrieved results.

• [ typesOnly = false ] {true|false} Indicates whether to return only attribute names in matching entries, or both attribute names and values.

• [ output = “JSON” ] {“JSON”|“LDIF”} Specifies the output format, which can be JSON (default) or LDIF.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “matches” {array|string} An array containing the matching entries, each represented as an object containing the DN and attribute properties; empty if none were found. If the alternative LDIF output format was chosen, this will be an LDIF string containing the matching entries.

• “referrals” {array} A string array of the referral URLs, empty if none were returned.

• “page” {object} Optional, included only for Paged Result searches:

  • “more” {true|false} Indicates whether there are more results to return as part of this search.

  • “totalEntryCount” {integer} The estimated number of entries in the complete result set. Note that some directories may not provide such an estimate and return zero in all cases.

  • “cookie” {string} Contains a string that must be passed back to the server with the subsequent search request to retrieve the next page (see the page.cookie parameter). If this was the last results page the string will be empty.

• “vlv” {object} Optional, included only for Virtual List View searches:

  • “totalEntryCount” {integer} The estimated number of entries in the complete result set.

  • “offset” {integer}

  • “cookie” {string} Contains a string that must be passed back to the server with the subsequent VLV search request (see the page.cookie parameter).

Examples:

Example request 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, 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 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:

{ "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 indicating all user entries should be sorted by surname and then by given name. Requires directory support of 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 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 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the entry in which to make the comparison.

• attribute {string} The attribute name for which to make the comparison.

• value {string} The assertion value to verify in the target entry.

• [ binary = false ] {true|false} If true the assertion value will be treated as a BASE-64 encoded binary value, if false it will be treated as text.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{true|false} Boolean true if there was a match, otherwise false.

Examples:

Example request, 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:

• CID {string} The connection identifier (CID).

• [ normalize = false ] {true|false} The default mode is to return the attribute names in the letter case specified in their directory schema definition. If true the attribute names will be returned in lower case.

• [ output = “JSON” ] {“JSON”| “LDIF”} Specifies the output format, which can be JSON (default) or LDIF.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{ object | string | null } A JSON object containing the root DSE attributes as attribute name/value array pairs. If the alternative output format was chosen, the result will be an LDIF string. If the root DSE is not available the result will be null.

Examples:

Example request 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 OpenDS 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" }

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 an 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) for the entry to add.

• [ attributes = {} ] {object} A JSON object specifying the attributes of the entry. Use name/string pairs for single-valued attributes and name/string array pairs for multi-valued attributes. Note that all attribute values must be specified as JSON strings. If this parameter is empty or omitted no text attributes will be added.

• [ binaryAttributes = {} ] {object} A JSON object specifying the binary attributes of the entry. Use name/string pairs for single-valued attributes and name/string array pairs for multi-valued attributes. The attribute values must be BASE-64 encoded strings. If this parameter is empty or omitted no binary attributes will be added.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• LDIF {string} An LDIF string representing a changetype ADD record.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the entry to delete.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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 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.delete (LDIF)

Deletes a directory entry specified by an LDIF string. Since v3.4.

Parameters:

• CID {string} The connection identifier (CID).

• LDIF {string} An LDIF string representing a changetype DELETE record.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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",
                "LDIF" : "dn: uid=user.9999,ou=people,dc=example,dc=com\n
                          changetype: delete\n" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the base entry to delete.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the entry to modify.

• attribute {string} The name of the attribute to update.

• type {“ADD”|“DELETE”|“REPLACE”|“INCREMENT”} The type of change to apply:

  • “ADD” Indicates that the provided value(s) should be added to the specified attribute in the target entry. If the attribute does not already exist, it will be created. If it does exist, then the new values will be added to the existing values. At least one value must be provided with the “ADD” modification type, and none of those values will be allowed to exist in the entry.

  • “DELETE” Indicates that the specified attribute or attribute values should be removed from the entry. If no values are provided, then the entire attribute will be removed. If one or more values are given, then only those values will be removed. If any values are provided, then all of those values must exist in the target entry.

  • “REPLACE” Indicates that the set of values for the specified attribute should be replaced with the provided value(s). If no values are given, then the specified attribute will be removed from the entry if it exists, or no change will be made. If one or more values are provided, then those values will replace the existing values if the attribute already exists, or a new attribute will be added with those values if there was previously no such attribute in the entry.

  • “INCREMENT” Indicates that the value of the specified attribute should be incremented. The target entry must have exactly one value for the specified attribute and it must be an integer. The modification must include exactly one value, and it must be an integer which specifies the amount by which the existing value is to be incremented (or decremented, if the provided value is negative).

• [ values = [] ] {array} One or more optional attribute values for this modification (if required by its type). None if empty or omitted.

• [ binary = false ] {true|false} If true the value(s) will be treated as BASE-64 encoded binary value(s).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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 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 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:

• CID {string} The connection identifier (CID).

• DN {string} The distinguished name (DN) of the entry to modify.

• mods {array} Array of one or more modification specification objects:

  • attribute {string} The name of the attribute to update.

  • type {“ADD”|“DELETE”|“REPLACE”|“INCREMENT”} The type of change to apply:

    • “ADD” Indicates that the provided value(s) should be added to the specified attribute in the target entry. If the attribute does not already exist, it will be created. If it does exist, then the new values will be added to the existing values. At least one value must be provided with the “ADD” modification type, and none of those values will be allowed to exist in the entry.

    • “DELETE” Indicates that the specified attribute or attribute values should be removed from the entry. If no values are provided, then the entire attribute will be removed. If one or more values are given, then only those values will be removed. If any values are provided, then all of those values must exist in the target entry.

    • “REPLACE” Indicates that the set of values for the specified attribute should be replaced with the provided value(s). If no values are given, then the specified attribute will be removed from the entry if it exists, or no change will be made. If one or more values are provided, then those values will replace the existing values if the attribute already exists, or a new attribute will be added with those values if there was previously no such attribute in the entry.

    • “INCREMENT” Indicates that the value of the specified attribute should be incremented. The target entry must have exactly one value for the specified attribute and it must be an integer. The modification must include exactly one value, and it must be an integer which specifies the amount by which the existing value is to be incremented (or decremented, if the provided value is negative).

  • [ values = [] ] {array} One or more optional attribute values for this modification (if required by its type). None if empty or omitted.

  • [ binary = false ] {true|false} If true the value(s) will be treated as BASE-64 encoded binary value(s).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• LDIF {string} An LDIF string representing a changetype MODIFY record.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

Example request 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:

• CID {string} The connection identifier (CID).

• DN {string} The current distinguished name (DN) of the entry to rename and/or move.

• newRDN {string} The new relative distinguished name (RDN) for the target entry.

• [ deleteOldRDN = false ] {true|false} Indicates whether to delete the current RDN value from the target entry.

• [ newSuperiorDN = null ] {string} The new superior DN for the entry. If null the entry is not to be moved below a new parent.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

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

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:

• CID {string} The connection identifier (CID).

• [ userID = null ] {string} The user for which to change the password. It should generally be the distinguished name (DN) of the target user (the specification may allow other values). If no value is provided the server will attempt to change the password for the currently authenticated user.

• [ oldPassword = null ] {string} The current password for the user. Some servers may require that the old password be provided when a user is changing their own password. Generally not necessary when an administrator is resetting the password for another user.

• [ newPassword = null ] {string} The new password for the user. If no value is provided the server may attempt to generate a new password for the user, and in that case it will be included in result. Note that some servers may not support generating a new password, in which case the client will always be required to provide it.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} If the LDAP server generated a new password, it will be provided in the response 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 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:

• CID {string} The connection identifier (CID).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} The current authorisation identity associated with the client connect, typically the distinguished name (DN) of the bound user. An empty string normally indicates an anonymous user.

Examples:

Example request:

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

Example response:

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

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:

• CID {string} The connection identifier (CID).

• name {string} The name or OID of the object class to retrieve.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “OID” {string} The object identifier (OID) for the object class.

• “names” {array} A string array with the names for the object class.

• “description” {string} The object class description, may be null.

• “obsolete” {true|false} Boolean true if this object class is declared obsolete, false if not.

• “type” {string} A string specifying the object class type, which can be “ABSTRACT”, “STRUCTURAL” or “AUXILIARY”. If not defined the value will be null.

• “requiredAttributes” {array} A string array with the names or OIDs of the attributes that are required to be present in entries containing the object class.

• “optionalAttributes” {array} A string array with the names or OIDs of the attributes that may optionally be present in entries containing the object class.

• “superClasses” {array} A string array with the names or OIDs of the superior classes for the object class, if available.

• “rawDefinition” {array} The string representation of the object class, in the format described in RFC 4512 section 4.1.1.

Examples:

Example request 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:

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

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} The DN of the entry for which to retrieve the governing schema. It may be null or an empty string in order to retrieve the schema that governs the server’s root DSE.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{array} A JSON array of the object classes, each defined as a JSON object with properties:

• “OID” {string} The object identifier (OID) for the object class.

• “names” {array} A string array with the names for the object class.

• “description” {string} The object class description, may be null.

• “obsolete” {true|false} Boolean true if this object class is declared obsolete, false if not.

• “type” {string} A string specifying the object class type, which can be “ABSTRACT”, “STRUCTURAL” or “AUXILIARY”. If not defined the value will be null.

• “requiredAttributes” {array} A string array with the names or OIDs of the attributes that are required to be present in entries containing the object class.

• “optionalAttributes” {array} A string array with the names or OIDs of the attributes that may optionally be present in entries containing the object class.

• “superClasses” {array} A string array with the names or OIDs of the superior classes for the object class, if available.

• “rawDefinition” {string} The string representation of the object class, in the format described in RFC 4512 section 4.1.1.

Examples:

Example request:

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

• CID {string} The connection identifier (CID).

• name {string} The name or OID of the attribute type to retrieve.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “OID” {string} The object identifier (OID) for the attribute type.

• “names” {array} A string array with the names for the attribute type.

• “description” {string} The attribute type description, may be null.

• “usage” {string} A string specifying the usage for the attribute type, which can be “userApplications”, “directoryOperations”, “distributedOperation” or “dSAOperation”.

• “obsolete” {true|false} Boolean true if the object class is declared obsolete, false if not.

• “singleValued” {true|false} Boolean true if the attribute type is declared single-valued, false if not.

• “readOnly” {true|false} Boolean true if the attribute type is declared no-user-modification, false if not.

• “collective” {true|false} Boolean true if the attribute type is declared collective, false if not.

• “syntaxOID” {string} The OID of the syntax for the attribute type, or null if the syntax is inherited.

• “equalityMatch” {string} The name or OID of the equality matching rule for this attribute type, or null if no equality matching rule is defined or a default rule is inherited.

• “orderingMatch” {string} The name or OID of the ordering matching rule for this attribute type, or null if no ordering matching rule is defined or a default rule is inherited.

• “substringMatch” {string} The name or OID of the substring matching rule for this attribute type, or null if no substring matching rule is defined or a default rule is inherited.

• “superType” {string} The name or OID of the superior type for this attribute type, or null if no superior type is defined.

• “rawDefinition” {string} The string representation of the object class, in the format described in RFC 4512 section 4.1.2.

Examples:

Example request:

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

The response:

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

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} The DN of the entry for which to retrieve the governing schema. It may be null or an empty string in order to retrieve the schema that governs the server’s root DSE.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{array} A JSON array of the attribute types, each defined as a JSON object with properties:

• “OID” {string} The object identifier (OID) for the attribute type.

• “names” {array} A string array with the names for the attribute type.

• “description” {string} The attribute type description, may be null.

• “usage” {string} A string specifying the usage for the attribute type, which can be “userApplications”, “directoryOperations”, “distributedOperation” or “dSAOperation”.

• “obsolete” {true|false} Boolean true if the object class is declared obsolete, false if not.

• “singleValued” {true|false} Boolean true if the attribute type is declared single-valued, false if not.

• “readOnly” {true|false} Boolean true if the attribute type is declared no-user-modification, false if not.

• “collective” {true|false} Boolean true if the attribute type is declared collective, false if not.

• “syntaxOID” {string} The OID of the syntax for the attribute type, or null if the syntax is inherited.

• “equalityMatch” {string} The name or OID of the equality matching rule for this attribute type, or null if no equality matching rule is defined or a default rule is inherited.

• “orderingMatch” {string} The name or OID of the ordering matching rule for this attribute type, or null if no ordering matching rule is defined or a default rule is inherited.

• “substringMatch” {string} The name or OID of the substring matching rule for this attribute type, or null if no substring matching rule is defined or a default rule is inherited.

• “superType” {string} The name or OID of the superior type for this attribute type, or null if no superior type is defined.

• “rawDefinition” {string} The string representation of the object class, in the format described in RFC 4512 section 4.1.2.

Examples:

Example request:

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

• CID {string} The connection identifier (CID).

• name {string} The name or OID of the matching rule to retrieve.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “OID” {string} The object identifier (OID) for the matching rule.

• “names” {array} A string array with the names for the matching rule.

• “description” {string} The matching rule description, may be null.

• “obsolete” {true|false} Boolean true if the matching rule is declared obsolete, false if not.

• “syntaxOID” {string} The OID of the syntax for the matching rule.

• “rawDefinition” {string} The string representation of the matching rule, in the format described in RFC 4512 section 4.1.3.

Examples:

Example request:

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

The response:

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

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} The DN of the entry for which to retrieve the governing schema. It may be null or an empty string in order to retrieve the schema that governs the server’s root DSE.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{array} A JSON array of the matching rules, each defined as a JSON object with properties:

• “OID” {string} The object identifier (OID) for the matching rule.

• “names” {array} A string array with the names for the matching rule.

• “description” {string} The matching rule description, may be null.

• “obsolete” {true|false} Boolean true if the matching rule is declared obsolete, false if not.

• “syntaxOID” {string} The OID of the syntax for the matching rule.

• “rawDefinition” {string} The string representation of the matching rule, in the format described in RFC 4512 section 4.1.3.

Examples:

Example request:

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

• CID {string} The connection identifier (CID).

• name {string} The name or OID of the matching rule use to retrieve.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “OID” {string} The object identifier (OID) for the matching rule use.

• “names” {array} A string array with the names for the matching rule use.

• “description” {string} The matching rule use description, may be null.

• “obsolete” {true|false} Boolean true if the matching rule use is declared obsolete, false if not.

• “applicableTypes” {array} A string array with the names or OIDs of the attribute types to which this matching rule use applies.

• “rawDefinition” {string} The string representation of the matching rule, in the format described in RFC 4512 section 4.1.4.

ldap.schema.getMatchingRuleUses

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

Parameters:

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} The DN of the entry for which to retrieve the governing schema. It may be null or an empty string in order to retrieve the schema that governs the server’s root DSE.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{array} A JSON array of the matching rule uses, each defined as a JSON object with properties:

• “OID” {string} The object identifier (OID) for the matching rule use.

• “names” {array} A string array with the names for the matching rule use.

• “description” {string} The matching rule use description, may be null.

• “obsolete” {true|false} Boolean true if the matching rule use is declared obsolete, false if not.

• “applicableTypes” {array} A string array with the names or OIDs of the attribute types to which this matching rule use applies.

• “rawDefinition” {string} The string representation of the matching rule, in the format described in RFC 4512 section 4.1.4.

ldap.schema.getSyntax

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

Parameters:

• CID {string} The connection identifier (CID).

• OID {string} The OID of the attribute syntax to retrieve.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} A JSON object with properties:

• “OID” {string} The object identifier (OID) for the attribute syntax.

• “description” {string} The attribute syntax description, may be null.

• “rawDefinition” {string} The string representation of the attribute syntax, in the format described in RFC 4512 section 4.1.5.

Examples:

Example request:

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

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

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} The DN of the entry for which to retrieve the governing schema. It may be null or an empty string in order to retrieve the schema that governs the server’s root DSE.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{array} A JSON array of the matching rule uses, each defined as a JSON object with properties:

• “OID” {string} The object identifier (OID) for the attribute syntax.

• “description” {string} The attribute syntax description, may be null.

• “rawDefinition” {string} The string representation of the attribute syntax, in the format described in RFC 4512 section 4.1.5.

Examples:

Example request:

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

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:

• DN {string} The DN string to validate.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{true|false} Boolean true if the provided string represents a valid DN, else false.

Examples:

Example request:

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

The response:

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

ldap.util.normalizeDN

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

Parameters:

• DN {string} The DN string to normalise.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} The normalised DN.

Examples:

Example request:

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

The response:

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

• DN1 {string} The first DN string to compare.

• DN2 {string} The second DN string to compare.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{integer} A negative integer if the first DN should come before the second DN in a sorted list, a positive integer if the first DN should come after the second DN in a sorted list, or zero if the two DN values can be considered equal.

Examples:

Example request:

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

The response:

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

ldap.util.isValidFilter

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

Parameters:

• filter {string} The search filter to test.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{true|false} Boolean true if the string was a valid search filter, else false.

Examples:

Example request:

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

The response:

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

• value {string} The filter assertion value to encode.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} The encoded search filter assertion value.

Examples:

Example request:

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

The response:

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

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 supports 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:

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object with properties:

• “N” {string} The safe prime ‘N’, in hexadecimal encoding.

• “g” {string} The generator ‘g’ parameter, in hexadecimal encoding.

• “H” {string} The hash algorithm ‘H’.

• “saltSize” {integer} The preferred salt ‘s’ size, in bytes.

• “x” {string} Explanation of the routine for computing the password key ‘x’.

• “M1” {string} Explanation of the routine for computing the server evidence message ‘M1’.

• “M2” {string} Explanation of the routine for computing the client evidence message ‘M2’.

Examples:

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

Parameters:

• CID {string} The connection identifier (CID).

• DN | username {string} Specifies the authenticating user identity, either by distinguished name (DN) or by username. If a username is specified the LDAP directory must be able to resolve it to a unique directory entry (by means of a plain SASL bind with username authzId).

• [ returnAuthzId = false ] {true|false} If true the resulting authorisation identity (authzId) of the LDAP connection will be returned in the step 2 response. Requires directory support of the Authorisation Identity control (RFC 3829).

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object with properties:

• “N” {string} The safe prime ‘N’, in hexadecimal encoding.

• “g” {string} The generator ‘g’ parameter, in hexadecimal encoding.

• “H” {string} The hash algorithm ‘H’.

• “B” {string} The public server value ‘B’, in hexadecimal encoding.

• “s” {string} The password salt ‘s’, in hexadecimal encoding.

Examples:

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:

• CID {string} The connection identifier (CID).

• A {string} The public client value ‘A’, in hexadecimal encoding.

• M1 {string} The client evidence message ‘M1’, in hexadecimal encoding. Its value must be computed according to the ‘M1’ routine advertised by x.srp6.getSettings.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} JSON object with properties:

• “M2” {string} The server evidence message ‘M2’, in hexadecimal encoding. Its value is computed according to the ‘M1’ routine advertised by x.srp6.getSettings.

• “authzId” {string} The authorisation identity (authzId) of the LDAP connection, if requested with the returnAuthzId parameter at step 1. The value will be null if the authzId was requested but the control is not supported by the directory server.

Examples:

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:

• CID {string} The connection identifier (CID).

• [ DN = null ] {string} Optional parameter, allows a different target user than the caller to be specified.

• s {string} The password salt ‘s’, in hexadecimal encoding. Its byte size must equal the preferred salt byte size advertised by x.srp6.getSettings.

• v {string} The password verifier ‘v’, in hexadecimal encoding. Its value must be computed according to the ‘x’ routine advertised by x.srp6.getSettings.

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{null} This method doesn’t return a result on success.

Examples:

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

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:

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} A string identifying the gateway software, set to “Json2Ldap”.

Examples:

Example request:

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

The response:

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

ws.getVersion

Reports the version of the web service software.

Parameters:

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} A string identifying the version, e.g. “2.1 (2011-12-06)”.

Examples:

Example request:

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

The response:

{ "result"  : "3.3 (2020-02-25)",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ws.getTime

Reports the local web service time in ISO 8601 format yyyy-MM-dd'T'HH:mm:ssZ (UTC timezone), for example “2010-03-31T23:59:59Z”.

Parameters:

• [ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} The local web service time with timezone offset.

Examples:

Example request:

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

The response:

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