LdapAuth datasheet

JSON web service for LDAP user authentication and provisioning

LdapAuth is a lightweight JSON-RPC 2.0 web service for authenticating and provisioning users whose accounts are stored in an LDAP v3 compatible directory.

Directory server compatibility

LdapAuth is compatible with directories supporting the current version 3 of the Lightweight Directory Access Protocol (LDAP).

Popular proprietary directory servers:

Popular open source directory servers:

Web API

The LdapAuth web API handles requests for user authentication and for retrieving selected user details for the purpose of provisioning.

User authentication and details » User realm » Web service information »
Monitoring »

Deployment

LdapAuth is packaged as a standard web application archive (WAR) ready for immediate deployment.

Runtime requirements:

Configuration

LdapAuth allows for comprehensive configuration through a set of properties located in the WEB-INF/authService.properties file.

Access control » Web API settings »

Allows / denies access to AuthService based on a set of rules such as SSL/X.509 security or client IP whitelist.

AuthService settings for enabling / disabling calls, exception reporting and HTTP response content type.

Authenticating backend » User DN resolution »

Specifies the authenticating realm and backend type.

Configures resolution of user DNs from the supplied username, email or other unique user identifier.

Json2Ldap gateway / proxy »

The Json2Ldap URL and other connection details.

LDAP server » User attributes for retrieval »

The LDAP directory URL and other connection details.

The names of the LDAP attributes to retrieve on a successfully authenticated user.get request.

Custom trust and key store »

Custom trust or key store for TLS/SSL LDAP connections.

Logging

LdapAuth uses the popular log4j framework. Here are the event types that can be selectively logged (at various levels):

  • On a HTTP request: method name, client IP, client X.509 certificate principal.

  • On a JSON-RPC 2.0 request: method name, request parameters (passwords are hidden), response status (success or error code).

  • DN resolution operation.

  • LdapAuth, Json2Ldap and LDAP exceptions.

Logging is configured by the WEB-INF/log4j.xml file.

Example LDAP directory server

An example LDAP directory server is included in the LdapAuth WAR to enable evaluation and testing of the service without an external directory. The example directory is enabled / disabled and configured through the WEB-INF/exampleDirectory.properties file.

System requirements and dependencies

LdapAuth requires a web server conforming to the Java servlet specification, such as Apache Tomcat or Jetty:

  • Java 1.6+

  • Java servlet API 3.0+

User store and authentication:

All package dependencies are conveniently included in the LdapAuth WAR distribution.

Change log

  • version 1.0 (2011-03-16)
    • First official and stable release.
  • version 1.1 (2011-03-27)
    • Renames the named "username" parameter to the shorter "user" ("user.auth" and "user.get" JSON-RPC).
    • Adds configuration parameter "authService.clients.responseContentType".
    • Adds Cross-Origin Resource Sharing (CORS) support.
  • version 1.1.1 (2011-05-20)
    • Updates JSON-RPC 2.0 Base JAR to 1.16.
  • version 1.1.2 (2011-06-14)
    • Thread-safe parsing of JSON-RPC 2.0 requests.
    • Updates JSON-RPC 2.0 Base JAR to 1.17 (JSON Smart).
    • Updates UnboundID SDK JAR to 2.2.0.
    • Updates JSON-RPC 2.0 Shell to 1.7.
  • version 1.2 (2011-07-12)
    • Renames configuration parameter authService.clients.requireHTTPS to authService.clients.requireSecureAccess to allow for alternative secure channel protocols besides HTTPS.
    • Updates JSON Smart JAR to 1.0.9.
    • Updates JSON-RPC 2.0 Base JAR to 1.21.
    • Updates JSON-RPC 2.0 Server JAR to 1.4.1.
    • Updates JSON-RPC 2.0 Shell to 1.9.
  • version 1.3 (2011-12-16)
    • Updates DN-Resolver JAR to 1.2.
    • Updates UnboundID SDK JAR to 2.3.0.
    • Updates JSON Smart JAR to 1.0.9-1.
    • Updates JSON-RPC 2.0 Base JAR to 1.24.
    • Updates Property Util JAR to 1.5.
    • Updates CORS Filter JAR to 1.3.1.
    • Updates JSON-RPC 2.0 Shell to 1.12.
  • version 2.0 (2012-02-20)
    • Introduces support for a Json2Ldap authentication backend in addition to direct LDAP connections.
    • Changes signature of user.auth and user.get JSON-RPC 2.0 requests and responses.
    • Adds support for returning multi-valued user entry attributes.
    • Refactors code to use the common NimbusDS package.
    • Updates DN-Resolver JAR to 1.3.
    • Updates JSON Smart JAR to 1.1.
    • Updates JSON-RPC 2.0 Base JAR to 1.25.
    • Updates JSON-RPC 2.0 Server JAR to 1.5.
  • version 2.0.1 (2012-04-03)
    • UTF-8 becomes the default and required character encoding for all JSON-RPC 2.0 responses. This is achieved by making "charset=utf-8" a mandatory part of the authService.clients.responseContentType configuration property.
    • Updates JSON Smart JAR to 1.1.1.
    • Updates JSON-RPC 2.0 Base JAR to 1.25.1.
    • Updates JSON-RPC 2.0 Client JAR to 1.7.1.
    • Updates JSON-RPC 2.0 Server JAR to 1.5.
  • version 2.1 (2012-06-29)
    • Makes AuthConnector and dependant classes public.
    • Adds support for arbitrary configuration properties prefixes.
    • Updates NimbusDS-Common JAR to 1.6.
    • Updates UnboundID SDK JAR to 2.3.1.
  • version 2.1.1. (2012-06-30)
    • Makes AuthConnector a base abstract class.
    • Introduces fine grained AuthConnector configuration.
  • version 2.1.2 (2012-07-03)
    • Exposes library APIs to allow AuthService to be embedded into web services and applications.
  • version 2.2 (2012-08-08)
    • UTF-8 is used for all attribute values returned by user.get, BASE64 encoding of non-ASCII values is deprecated.
    • Adds API key support through the JSON-RPC 2.0 Access Filter library.
    • Updates NimbusDS Common JAR to 1.11.
    • Updates JSON-RPC 2.0 Base JAR to 1.27.
    • Updates JSON-RPC 2.0 Server JAR to 1.6.
    • Updates JSON-RPC 2.0 Client JAR to 1.7.2.
    • Updates Property Util JAR to 1.6.
    • Updates CORS Filter JAR to 1.3.2.
    • Updates Log4j JAR to 1.2.17.
  • version 2.3 (2012-08-22)
    • Adds JSON-RPC 2.0 realm.get method to retrieve the name of the authenticating realm.
  • version 2.3.1 (2012-08-23)
    • Updates JSON-RPC 2.0 Access Filter JAR to 1.3.
  • version 2.4 (2012-08-28)
    • Adds authService.json2ldap.connectTimeout configuration option.
    • Adds authService.json2ldap.readTimeout configuration option.
    • Rewrites AuthService JSON-RPC 2.0 error codes and messages.
    • Exports com.nimbusds.authservice.AuthService instance to servlet context as nimbusDS.authService attribute.
    • Updates NimbusDS Common JAR to 1.14.
    • Updates JSON-RPC 2.0 Server JAR 1.7.
    • Updates JSON-RPC 2.0 Client JAR to 1.8.
  • version 2.4.1 (2012-08-29)
    • Minor documentation and packaging updates.
  • version 2.5 (2012-08-31)
    • Adds example in-memory directory server for demo and testing purposes.
    • Renames configuration file from authservice.properties to authService.properties.
    • Updates NimbusDS Common JAR to 1.15.
  • version 2.6 (2012-09-11)
    • Adds JSON-RPC 2.0 user.resolveDN method to resolve a user’s distinguished name (DN) by username.
  • version 2.7 (2012-09-12)
    • Renames previous JSON-RPC 2.0 user.get method to user.authGet.
    • Adds JSON-RPC 2.0 user.get method to retrieve a user’s distinguished name (DN) and selected attributes by username only.
    • Renames configuration property authService.api.allowDNProvision to authService.api.enableDNProvision.
    • Renumbers AuthService JSON-RPC 2.0 error codes.
  • version 2.7.1 (2012-09-12)
    • Fixes duplicate -3031 AuthService error bug.
  • version 2.8 (2012-10-03)
    • Fixes null pointer bug in user attributes processing.
    • Moves Json2Ldap web service detection routine to a separate thread.
    • Updates NimbusDS Common JAR to 1.16.
  • version 2.8.1 (2012-10-30)
    • Increases max wait time for LDAP search connection pool to 1000ms.
  • version 2.9 (2012-12-04)
    • Renames authService.ldapServer.searchConnectionPoolSize configuration property authService.ldapServer.connectionPoolSize.
    • Adds authService.ldapServer.connectionPoolMaxWaitTime configuration property (defaults to 500ms).
    • Upgrades NimbusDS Common JAR to 1.42.
    • Upgrades JSON-RPC 2.0 Base JAR to 1.30.
    • Upgrades JSON-RPC 2.0 Client JAR to 1.8.
    • Upgrades JSON-RPC 2.0 Server JAR to 1.9.
    • Upgrades CORS Filter JAR to 1.5.
    • Upgrades JSON-RPC 2.0 Shell to 1.15.
  • version 2.9.1 (2012-12-08)
    • Fixes support for the authService.ldapServer.searchConnectionPoolSize configuration parameter.
  • version 2.9.2 (2012-12-13)
    • Adds missing optional LDAP server connection parameters to authService.properties.
    • Sets default authService.ldapServer.connectTimeout parameter to 0 ms.
  • version 2.10 (2013-01-04)
    • Factors out LDAP connection factory (NimbusDS Common 1.50).
    • Upgrades NimbusDS Common JAR to 1.52.
    • Upgrades JSON-RPC 2.0 Base JAR to 1.31.
    • Upgrades JSON-RPC 2.0 Client JAR to 1.11.
  • version 3.0 (2014-02-20)
    • Renames to LdapAuth service.
    • Rebrands for new Connect2id Ltd. company name.
    • Upgrades Common JAR to 1.76.1.
    • Upgrades CORS Filter JAR to 1.9.2.
  • version 3.0.1 (2014-04-08)
    • Upgrades Common JAR to 1.76.2.
    • Upgrades UnboundID LDAP SDK to 2.3.6.
    • Upgrades DN Resolver to 1.3.2.
  • version 3.1 (2015-03-10)
    • Fixes resource paths in web.xml for Tomcat 8 (issue #14).
    • Upgrades Common JAR to 1.89.
    • Upgrades UnboundID LDAP SDK to 2.3.8.
    • Upgrades Log4j to 2.1.
    • Upgrades CORS Filter to 2.3.
  • version 3.2 (2015-03-11)
    • Adds monitor.usage.getStats RPC.
    • Adds monitor.directoryConnector.getStats RPC.
    • Adds monitor.directoryConnector.resetStats RPC.
  • version 3.2.1 (2015-03-13)
    • Upgrades to Common JAR 1.89.3 (fixes missing LDAP connection pool metric).
  • version 3.3 (2016-12-13)
    • Upgrades to UnboundID LDAP SDK 3.2.0.
    • Upgrades to JSON Smart 1.3.1.
    • Upgrades Common JAR to 2.2.
    • Upgrades JSON-RPC 2.0 Base JAR to 1.38.
    • Upgrades JSON-RPC 2.0 Client JAR to 1.16.4.
    • Upgrades Dropwizard Metrics to 3.1.2.
    • Upgrades CORS Filter to 2.5.
    • Upgrades to Log4j 2.7.
  • version 3.4 (2016-12-13)
    • Upgrades to Java 8.
  • version 3.5 (2016-01-17)
    • Enables set up of LDAP operations in the example LDAP directory server.
    • Upgrades Common JAR to 2.3.