LdapAuth quick start

1. Download and unzip

Extract the downloaded LdapAuth ZIP package to a directory on your computer.

2. Deploy

The LdapAuth web service and its configuration files are packaged in a Java web application archive named ldapauth.war.

LdapAuth requires Java 17 or later and a web container implementing Jakarta Servlet 6.0. Suitable choices include Apache Tomcat 10.1 and Jetty 12 configured for Jakarta EE 10.

With a standard Tomcat installation, copy ldapauth.war to Tomcat’s webapps/ directory. Tomcat deploys the application at /ldapauth/ and, with its default deployment settings, extracts it to webapps/ldapauth/.

For another container, follow its WAR deployment instructions.

3. Verify

Open the LdapAuth URL in a browser. For a local Tomcat installation listening on port 8080, use:

http://localhost:8080/ldapauth/

If the service is running, the page displays a message beginning:

Use HTTP POST to submit your JSON-RPC 2.0 request

It also identifies the running LdapAuth version and lists the available JSON-RPC methods. The exact output depends on the version and configuration.

4. Configure

The configuration file is located in the deployed application’s WEB-INF directory. With the Tomcat deployment described above, its path is:

webapps/ldapauth/WEB-INF/ldapAuth.properties

The default configuration points to a sample LDAP directory included with LdapAuth, so you can try the API before connecting it to your own directory.

For production use, edit the configuration to specify your LDAP server’s host, port and connection settings. You will also need to configure:

• API access and security, such as allowed client IP addresses and API keys.
• How usernames are resolved to LDAP distinguished names (DNs).
• Which user attributes to return, if required.

See the configuration manual for details. Restart LdapAuth after changing its configuration.

5. Use

The web API reference describes the JSON-RPC 2.0 methods supported by LdapAuth.

You can try the service with the JSON-RPC 2.0 Shell included in the downloaded ZIP. Start it with the URL of your LdapAuth instance:

java -jar jsonrpc2-shell.jar --auto-id 0 http://localhost:8080/ldapauth/

The --auto-id 0 option adds a request ID automatically, so you do not need to enter one for each call.

With the sample LDAP directory configured, try these methods:

• ws.getName — Identify the web service.
• user.auth — Authenticate alice.
• user.authGet — Authenticate alice and, on success, return selected attributes from her directory entry.

JSON-RPC 2.0 > ws.getName
LdapAuth

JSON-RPC 2.0 > user.auth {"username":"alice","password":"secret"}
true

JSON-RPC 2.0 > user.authGet {"username":"alice","password":"secret"}
{
  "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"
    ]
  }
}

Use HTTPS when sending credentials to a service outside your local test environment. The JSON-RPC 2.0 Shell manual describes its other command-line options.

6. Questions?

Contact support if you need help configuring LdapAuth or integrating its web API with your application.