Web API

LdapAuth speaks JSON-RPC 2.0, the latest version of the protocol for remote procedure calls (RPC) using JSON-encoded messages. Clients can send their requests to an LdapAuth service by HTTP POST.

Overview of the LdapAuth web API:

User authentication and details »	User realm »	Web service information »
user.auth user.authGet user.get user.resolveDN	realm.get	ws.getName ws.getVersion ws.getTime
Monitoring »
monitor.usage.getStats monitor.directoryConnector.getStats monitor.directoryConnector.resetStats

Each JSON-RPC 2.0 request consists of the following fields:

The requested method name, e.g. "user.auth" or "user.get".
The method parameters (if any).
An arbitrary request ID which is echoed back to the client.
A string identifying the JSON-RPC protocol version as “2.0”.

Example JSON-RPC 2.0 request for simple user authentication:

{
  "method"  : "user.auth",
  "params"  : { "username" : "alice",
                "password" : "secret" },
  "id"      : "0001",
  "jsonrpc" : "2.0"
}

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 LdapAuth will take their default value (given after the equals sign).

Note: LdapAuth 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.

User authentication and details

LdapAuth provides two JSON calls for user authentication: user.auth which simply verifies the supplied username and password, and user.authGet which, in addition to that, also retrieves a set of user attributes (such as the person’s name, email address, phone numbers, photo, etc.) from the LDAP directory.

The special user.get calls allows direct retrieval of a user’s directory DN and attributes, without the user’s password.

Finally, user.resolveDN can be used to find out the directory DN for a given username.

user.auth

Authenticates a user with the specified username and password. Returns true on success or false if the credentials are invalid.

Parameters:

username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry (DN) in the back-end LDAP directory. See DN resolution configuration for details.
password {string} The user password (case sensitive).
[ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{true|false} Boolean true if the username / password combination is correct, else false.

Examples:

Example request to authenticate a user with email alice@wonderland.net and password secret:

{ "method"  : "user.auth",
  "params"  : { "username" : "alice@wonderland.net",
                "password" : "secret" },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Response indicating the credentials were valid:

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

Response indicating either the username or the password or both were invalid:

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

If for some reason the LdapAuth couldn’t process the request (due to bad configuration, the LDAP server being down or other exception) a JSON-RPC error is returned to the client. How verbose the returned error message is depends on the ldapAuth.api.exposeExceptions configuration setting. You may also check the full listing of LdapAuth error codes and messages.

{ "error"   : { "message" : "Trusted client X.509 certificate required",
                "code"    : -31110 },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

user.authGet

Authenticates a user with the specified username and password.

If the credentials are valid returns the user’s directory attributes specified by the ldapAuth.userAttributes configuration setting. DN provisioning and Json2Ldap CID provisioning may also be available to clients if configured.

If the username / password combination is invalid this call returns a -2000 “Invalid credentials” error.

Parameters:

username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry (DN) in the back-end LDAP directory. See DN resolution configuration for details.
password {string} The user password (case sensitive).
[ returnJson2LdapCID = false ] {true|false} Optional parameter for requesting an LDAP connection bound as the authenticated user. The connection will be represented as a Json2Ldap connection identifier (CID). Requires Json2Ldap CID provisioning to be enabled in the LdapAuth configuration.
[ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} Upon successful authentication, a JSON object with the following properties:

DN {string} If DN provisioning is enabled, the resolved distinguished name (DN) of the user. If the user DN could not be resolved the value is null.
attributes {object} The selected user attributes, as key / value pairs. The values are UTF-8 text encoded.
Json2Ldap {object} If requested, a JSON object with the following properties:
- URL {string} The URL of the Json2Ldap web service.
- CID {string} The Json2Ldap connection identifier (CID) bound as the authenticated user or null if a CID could not be obtained.

Examples:

Example request to authenticate and retrieve a user with username alice and password secret:

{ "method"  : "user.authGet",
  "params"  : { "username" : "alice",
                "password" : "secret" }
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Example response indicating authentication success and returning the user attributes according to the ldapAuth.userAttributes configuration setting. Multi-valued attributes are specified as arrays, even if they contain a single item.

{ "result"  : { "attributes" : { "userID" : "alice",
                                 "name"   : "Alice Adams",
				 "email"  : [ "alice@wonderland.net" ],
                                 "phone"  : [ "+1 685 622 6202",
				              "+1 010 154 3228",
					      "+1 225 216 5900" ] },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

If DN provisioning is enabled that distinguished name (DN) of the user in the directory is also included:

{ "result"  : { "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
                "attributes" : { "userID" : "alice",
                                 "name"   : "Alice Adams",
				 "email"  : [ "alice@wonderland.net" ],
                                 "phone"  : [ "+1 685 622 6202",
				              "+1 010 154 3228",
					      "+1 225 216 5900" ] } },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

And here is a user.authGet response with a Json2Ldap URL and connection identifier (CID) bound as the authenticated user:

{ "result"  : { "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
                "attributes" : { "userID" : "alice",
                                 "name"   : "Alice Adams",
				 "email"  : [ "alice@wonderland.net" ],
                                 "phone"  : [ "+1 685 622 6202",
				              "+1 010 154 3228",
					      "+1 225 216 5900" ] },
                "Json2Ldap" : { "URL" : "http:\/\/ldap.example.com",
		                "CID" : "9163a3c2-d15a-41af-9b7a-114afed7dd80" } },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Example JSON-RPC 2.0 error response indicating bad username and / or password:

{ "error"   : { "message" : "Bad username/password",
                "code"    : -2000 },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

user.get

If the username is valid, returns the user’s directory attributes specified by the ldapAuth.userAttributes configuration setting. DN provisioning may also be available to clients if configured.

If the username is invalid, i.e. no matching user entry was found in the backend LDAP directory, this call returns a null result.

The underlying LDAP queries are made over a search user connection and require a properly configured DN resolve method set to SEARCH.

user.get calls are disabled per default for security reasons. If allowed, access to user.get must be protected by an API key or similar method to ensure ensure that only authorised web clients can retrieve user attributes directly.

Parameters:

username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry (DN) in the back-end LDAP directory. See DN resolution configuration for details.
[ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{object} Upon successful authentication, a JSON object with the following properties:

DN {string} If DN provisioning is enabled, the resolved distinguished name (DN) of the user. If the user DN could not be resolved the value is null.
attributes {object} The selected user attributes, as key / value pairs. The values are UTF-8 text encoded.

Examples:

Example request to retrieve the details for username alice, bypassing password authentication of the target user. The call requires an API key to ensure that only authorised LdapAuth clients can access user data directly:

{ "method"  : "user.get",
  "params"  : { "username" : "alice",
                "apiKey" : "dfb398c96cf44d84aaa78c31f295e6a0" },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Example response, with the directory DN and selected attributes of alice:

{ "result"  : { "DN"         : "uid=alice,ou=people,dc=wonderland,dc=net",
                "attributes" : { "userID" : "alice",
                                 "name"   : "Alice Adams",
				 "email"  : [ "alice@wonderland.net" ],
                                 "phone"  : [ "+1 685 622 6202",
				              "+1 010 154 3228",
					      "+1 225 216 5900" ] } },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

user.resolveDN

Resolves the distinguished name (DN) for the specified username by making an LDAP query to the backend directory. Returns the matching DN or null if the username is invalid. Requires a properly configured DN resolution.

This call can be used to verify usernames or to find out a user’s DN in order to retrieve information about the user via Json2Ldap.

Parameters:

username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry (DN) in the back-end LDAP directory. See DN resolution configuration for details.
[ apiKey = null ] {string} Optional API key for the request, see API key configuration.

Result:

{string} The matching distinguished name (DN) for the username or null if none was found in the backend directory.

Examples

Request to get the DN for username alice:

{ "method"  : "user.resolveDN",
  "params"  : { "username" : "alice" }
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Example response returning a matching DN:

{ "result"  : "uid=alice,ou=people,dc=wonderland,dc=net",
  "id"      : "0001",
  "jsonrpc" : "2.0" }

If the username is invalid and doesn’t correspond to a user entry in the backend directory the result is null:

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

User realm

The user realm represents the complete user base for which an LdapAuth service provides authentication and details retrieval.

realm.get

Returns the name of the user realm, as configured by ldapAuth.authRealm.

Parameters:

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

Result:

{string} A string identifying the realm, empty if not specified.

Examples:

Example request message:

{ "method"  : "realm.get",
  "id"      : 1,
  "jsonrpc" : "2.0" }

Example response message identifying the user realm as “wonderland.net”:

{ "result"  : "wonderland.net",
  "id"      : 1,
  "jsonrpc" : "2.0" }

Monitoring

A set of JSON calls is available to monitor the usage of LdapAuth by clients and the condition of the LDAP connection pool to the backend directory. This data can be extremely useful to DevOps to keep an eye on the service performance and suspicious behaviour (e.g. brute force attacks on passwords).

monitor.usage.getStats

Returns statistics about successful and failed (due to bad credentials) authentication requests. Also returns metrics on the requests that failed to an internal error, e.g. the LDAP backend directory being unavailable.

Parameters:

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

Result:

{object} JSON object with the following members:
- successfulAuthRequests {object} JSON object with metrics about the successful authentication requests: * count {integer} The number of events. * m1_rate {float} The one-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the one-minute load average in the top Unix command. * m5_rate {float} The five-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the five-minute load average in the top Unix command. * m15_rate {float} The fifteen-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the fifteen-minute load average in the top Unix command. * mean_rate {float} The mean rate at which events have occurred since start up. * units = “events/second” The unit measure.
- successfulAuthRequests {object} JSON object with metrics about the failed (due to bad username / password) authentication requests: * count {integer} The number of events. * m1_rate {float} The one-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the one-minute load average in the top Unix command. * m5_rate {float} The five-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the five-minute load average in the top Unix command. * m15_rate {float} The fifteen-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the fifteen-minute load average in the top Unix command. * mean_rate {float} The mean rate at which events have occurred since start up. * units = “events/second” The unit measure.
- successfulAuthRequests {object} JSON object with metrics about the requests which couldn’t be fulfilled due to an internal error: * count {integer} The number of events. * m1_rate {float} The one-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the one-minute load average in the top Unix command. * m5_rate {float} The five-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the five-minute load average in the top Unix command. * m15_rate {float} The fifteen-minute exponentially-weighted moving average rate at which events have occurred since start up. This rate has the same exponential decay factor as the fifteen-minute load average in the top Unix command. * mean_rate {float} The mean rate at which events have occurred since start up. * units = “events/second” The unit measure.

Examples:

Example request to retrieve the current usage statistics:

{ "method"  : "monitor.usage.getStats",
  "params"  : { "apiKey" : "f70defbeb88141f88138bea52b6e1b9c" },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Response response:

{ "result"  : { "successfulAuthRequests" : { "count"     : 1,
                                             "m1_rate"   : 0.015991117074135343,
                                             "m5_rate"   : 0.0033057092356765017,
                                             "m15_rate"  : 0.0011080303990206543,
                                             "mean_rate" : 0.0001450647143651782,
                                             "units"     : "events\/second" },
                "badAuthRequests"        : { "count"     : 0,
                                             "m1_rate"   : 0.0,
                                             "m5_rate"   : 0.0,
                                             "m15_rate"  : 0.0,
                                             "mean_rate" : 0.0,
                                             "units"     : "events\/second" },
                "serverErrors"           : { "count"     : 0,
                                             "m1_rate"   : 0.0,
                                             "m5_rate"   : 0.0,
                                             "m15_rate"  : 0.0,
                                             "mean_rate" : 0.0,
                                             "units"     : "events\/second" } },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

monitor.directoryConnector.getStats

Returns statistics about the pool of LDAP connections to the backend directory. Applies only if the backend is configured as direct LDAP. If a Json2Ldap proxy / gateway is used instead, the call will return an -2033 “Directory connector stats not supported” error.

If you’re seeing a significant number of connections that have been checked out after waiting then you should consider increasing the size of the LDAP connection pool.

If you’re seeing a significant number of failed connections, then you might be experiencing network problems, or problems with the directory server itself.

Parameters:

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

Result:

{object} JSON object with the following members:
- ldapConnector.numAvailableConnections {integer} The number of connections currently available for use in the pool, if that information is available (else -1).
- ldapConnector.maxAvailableConnections {integer} The maximum number of connections that may be available in the pool at any time, if that information is available (else -1).
- ldapConnector.numSuccessfulConnectionAttempts {integer} The number of connections that have been successfully created for use in conjunction with the connection pool.
- ldapConnector.numFailedConnectionAttempts {integer} The number of failed attempts to create a connection for use in the connection pool.
- ldapConnector.numConnectionsClosedDefunct {integer} The number of connections that have been closed as defunct (i.e., they are no longer believed to be valid).
- ldapConnector.numConnectionsClosedExpired {integer} The number of connections that have been closed as expired (i.e., they have been established for longer than the maximum connection age for the pool).
- ldapConnector.numConnectionsClosedUnneeded {integer} The number of connections that have been closed as unneeded (i.e., they were created in response to heavy load but are no longer needed to meet the current load, or they were closed when the pool was closed).
- ldapConnector.numSuccessfulCheckouts {integer} The number of successful attempts to check out a connection from the pool (including connections checked out for internal use by operations processed as part of the pool).
- ldapConnector.numSuccessfulCheckoutsWithoutWaiting {integer} The number of successful attempts to check out a connection from the pool that were able to obtain an existing connection without waiting.
- numSuccessfulCheckoutsAfterWaiting {integer} The number of successful attempts to check out a connection from the pool that had to wait for a connection to become available.
- ldapConnector.numSuccessfulCheckoutsNewConnection {integer} The number of successful attempts to check out a connection from the pool that had to create a new connection because no existing connections were available.
- ldapConnector.numFailedCheckouts {integer} The number of failed attempts to check out a connection from the pool (including connections checked out for internal use by operations processed as part of the pool).
- ldapConnector.numReleasedValid {integer} The number of times a valid, usable connection has been released back to the pool after being checked out (including connections checked out for internal use by operations processed within the pool).

Examples:

Example request to retrieve the current LDAP connection pool statistics:

{ "method"  : "monitor.directoryConnector.getStats",
  "params"  : { "apiKey" : "f70defbeb88141f88138bea52b6e1b9c" },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Response response:

{ "result"  : { "ldapConnector.numSuccessfulConnectionAttempts"      : 1,
                "ldapConnector.numFailedConnectionAttempts"          : 0,
                "ldapConnector.numConnectionsClosedDefunct"          : 0,
                "ldapConnector.numConnectionsClosedExpired"          : 0,
                "ldapConnector.numConnectionsClosedUnneeded"         : 0,
                "ldapConnector.numSuccessfulCheckouts"               : 1,
                "ldapConnector.numSuccessfulCheckoutsWithoutWaiting" : 0,
                "ldapConnector.numSuccessfulCheckoutsNewConnection"  : 1,
                "ldapConnector.numFailedCheckouts"                   : 0,
                "ldapConnector.numReleasedValid"                     : 1,
                "ldapConnector.numAvailableConnections"              : 1,
                "ldapConnector.maxAvailableConnections"              : 10 },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

monitor.directoryConnector.resetStats

Resets the statistics about the pool of LDAP connections back to zero. Applies only if the backend is configured as direct LDAP. If a Json2Ldap proxy / gateway is used instead, the call will return an -2033 “Directory connector stats not supported” error.

Parameters:

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

Result:

null

Example request to reset the current LDAP connection pool statistics:

{ "method"  : "monitor.directoryConnector.resetStats",
  "params"  : { "apiKey" : "f70defbeb88141f88138bea52b6e1b9c" },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Response response indicating success:

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

Web service information

LdapAuth also provides three JSON calls 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 “LdapAuth”.

Examples:

Example request message:

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

The response message:

{ "result"  : "LdapAuth",
  "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. “3.0 (2014-02-20)”.

Examples:

Example request message:

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

The response message:

{ "result"  : "3.0 (2014-02-20)",
  "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 message:

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

The response message:

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