LdapAuth datasheet

JSON web service for LDAP user authentication and attribute retrieval

LdapAuth is a lightweight JSON-RPC 2.0 web service for authenticating users against an LDAPv3 directory and retrieving selected attributes from their directory entries.

Directory server compatibility

LdapAuth works with LDAPv3-compatible directories, including:

Json2Ldap compatibility

LdapAuth can also access directory servers via a Json2Ldap 2.3+ web API.

Web API

The LdapAuth web API supports user authentication, retrieval of selected user attributes, and service monitoring.

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 web application archive (WAR) for deployment in a Jakarta Servlet 6.0 container, such as Apache Tomcat 10.1. Java 17 or later is required. See the quick start guide for deployment instructions.

Configuration

LdapAuth is configured through the WEB-INF/ldapAuth.properties file. Configuration properties can be overridden by Java system properties.

Access control »	Web API settings »
Controls access to LdapAuth using rules for HTTPS, client X.509 certificates, allowed hosts and API keys. 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.*	Controls which API methods are available, exception reporting and the 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 how a username, email address or other unique identifier is resolved to a user DN. 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	Configures the LDAP attributes returned by user.authGet and user.get. authService.userAttributes.single.* authService.userAttributes.multi.*
Custom trust and key store »
Custom trust and key stores for TLS connections to the LDAP directory. 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 Log4j for logging. The following events can be logged at configurable levels:

HTTP requests: method name, client IP address and client X.509 certificate principal.
JSON-RPC 2.0 requests: method name, request parameters (with passwords hidden) and response status (success or error code).
DN resolution operations.
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. Configure or disable the sample directory through WEB-INF/sampleDirectory.properties.

System requirements

Runtime:

Java 17 or later
A Jakarta Servlet 6.0-compatible container