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:

• Active Directory from Microsoft

• eDirectory from Novell

• Tivoli Directory Server from IBM

Popular open source directory servers:

• OpenLDAP, the first influential open source implementation

• OpenDJ, originally from Sun and written in Java

• 389 Directory Server, a RedHat/Fedora project

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 »
user.auth user.authGet user.get user.resolveDN	realm.get	ws.getName ws.getTime ws.getVersion
Monitoring »
monitor.usage.getStats monitor.directoryConnector.getStats monitor.directoryConnector.resetStats

Deployment

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

Runtime requirements:

• Java 8
• Servlet 3.0+ compatible container, such as Apache Tomcat 8.

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.access.https.require authService.access.https.requireClientCert authService.access.https.clientCertPrincipal authService.access.hosts.allow authService.access.apiKeys.require authService.access.apiKeys.exemptedMethods authService.access.apiKeys.map.*	AuthService settings for enabling / disabling calls, exception reporting and HTTP response content type. authService.api.allowUserAuthRequests authService.api.allowUserAuthGetRequests authService.api.allowUserGetRequests authService.api.allowUserResolveDNRequests authService.api.enableDNProvision authService.api.allowJson2LdapCIDProvision authService.api.exposeExceptions authService.api.reportRequestProcTime authService.api.responseContentType
Authenticating backend »	User DN resolution »
Specifies the authenticating realm and backend type. authService.authRealm authService.authBackend	Configures resolution of user DNs from the supplied username, email or other unique user identifier. authService.dnResolution.method authService.dnResolution.dnTemplate authService.dnResolution.searchUserDN authService.dnResolution.searchUserPassword authService.dnResolution.searchBaseDN authService.dnResolution.searchScope authService.dnResolution.searchFilter
Json2Ldap gateway / proxy »
The Json2Ldap URL and other connection details. authService.json2ldap.url authService.json2ldap.useDefaultLDAPServer authService.json2ldap.trustSelfSignedCerts authService.json2ldap.connectTimeout authService.json2ldap.readTimeout
LDAP server »	User attributes for retrieval »
The LDAP directory URL and other connection details. authService.ldapServer.url authService.ldapServer.selectionAlgorithm authService.ldapServer.connectTimeout authService.ldapServer.security authService.ldapServer.trustSelfSignedCerts authService.ldapServer.connectionPoolSize authService.ldapServer.connectionPoolMaxWaitTime	The names of the LDAP attributes to retrieve on a successfully authenticated user.get request. authService.userAttributes.single.* authService.userAttributes.multi.*
Custom trust and key store »
Custom trust or key store for TLS/SSL LDAP connections. authService.customTrustStore.enable authService.customTrustStore.file authService.customTrustStore.type authService.customTrustStore.password authService.customKeyStore.enable authService.customKeyStore.file authService.customKeyStore.type authService.customKeyStore.password

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.

Sample LDAP directory server

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

System requirements and dependencies

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

• Java 8+

• Java Servlet API 3.1+

User store and authentication:

• LDAP v3 compatible directory

• Optional Json2Ldap gateway/proxy, version 2.3+

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.
• version 3.5.1 (2020-05-13)
  • Updates to UnboundID LDAP SDK 5.0.1.
  • Updates to Java Property Utils 1.15.
  • Updates JSON-RPC 2.0 Base to 1.38.1.
  • Updates JSON-RPC 2.0 Server to 1.11.
  • Updates JSON-RPC 2.0 Access Filter to 1.6.
  • Updates Dropwizard Metrics to 3.1.5.
  • Updates CORS Filter to 2.9.
  • Updates to Log4j 2.13.3.
• version 3.5.2 (2021-10-15)
  • Updates to UnboundID LDAP SDK 6.0.2.
  • Updates to Java Property Utils 1.16.
  • Updates JSON-RPC 2.0 Base to 2.0.
  • Updates JSON-RPC 2.0 Client to 1.16.5.
  • Updates JSON-RPC 2.0 Server to 1.11.1.
  • Updates JSON-RPC 2.0 Access Filter to 1.6.
  • Updates NimbusDS Common to 2.45.4.
  • Updates JSON Smart to 2.4.7.
  • Updates Dropwizard Metrics to 4.2.4.
  • Updates CORS Filter to 2.10.
  • Updates to Log4j 2.14.1.
• version 3.5.3 (2021-12-10)
  • Updates to UnboundID LDAP SDK 6.0.3.
  • Updates to Log4j 2.15.0.
• version 3.5.4 (2021-12-16)
  • Updates to com.thetransactioncompany:jsonrpc2-access-filter:1.7
  • Updates to javax.servlet:javax.servlet-api:3.1.0
  • Updates to io.dropwizard.metrics:metrics-core:4.2.6
  • Updates to Log4j 2.16.0.
• version 3.5.5 (2021-12-18)
  • Updates to Log4j 2.17.0.
• version 3.5.6 (2022-01-17)
  • Updates to com.thetransactioncompany:jsonrpc2-access-filter:1.7.1
  • Updates Dropwizard Metrics to 4.2.7.
  • Updates to Log4j 2.17.1.