Skip to content
Connect2id

Quick start

1. Download and unzip

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

2. Deploy

The LdapAuth web service and its configuration files are packaged in a standard WAR file called

ldapauth.war

Deploy this WAR file to a Java web server (requires Java 8 and Servlet 3.0+ compatible container). You can grab a free copy of the popular open-source Apache Tomcat or Jetty servers.

If you have Apache Tomcat, simply copy the WAR file to the webapps/ directory of your Tomcat installation. Tomcat will then automatically extract the content of the WAR into a directory called webapps/ldapauth/ and start the LdapAuth service.

Other web servers may have a different WAR deployment procedure, involving a web UI or the command line.

3. Verify

Point your web browser to the URL where the LdapAuth instance was installed, e.g. to

http://localhost:8080/ldapauth/

assuming the web server is on localhost and it is listening on port 8080.

If the LdapAuth is up and running the following banner message will appear in your browser:

Use HTTP POST to submit your JSON-RPC 2.0 request

Web service: LdapAuth, version 3.4 (2016-12-13)
Vendor: Connect2id Ltd., http://connect2id.com

Supported JSON-RPC 2.0 requests:
	* monitor.directoryConnector.getStats
	* monitor.directoryConnector.resetStats
	* monitor.usage.getStats
	* realm.get
	* user.auth
	* user.authGet
	* user.get
	* user.resolveDN
	* ws.getName
	* ws.getTime
	* ws.getVersion

It basically says that Json2Ldap expects JSON-RPC 2.0 requests received by HTTP POST and lists the available calls.

4. Configure

The LdapAuth configuration file is located in the WEB-INF directory of the deployed WAR package. On Apache Tomcat this is

webapps/ldapauth/WEB-INF/ldapAuth.properties

Out of the box LdapAuth comes with a default configuration which points to a sample LDAP directory server included with the service. With this sample directory you to easily test the LdapAuth web API and its capabilities.

For real use edit the LdapAuth configuration to point to your production LDAP server, by specifying its host, port number and other connection details (such as pooling). You will also need to configure the following:

  • Access and security (whitelisted IPs, API keys, etc).
  • The parameters for resolving usernames to directory entries (DNs).
  • Which user attributes to provision, if that is required.

Refer to the LdapAuth configuration manual for more information. If you need help get in touch with our support.

Remember to restart your LdapAuth service after updating the configuration!

5. Use

The web API reference of LdapAuth describes all JSON Remote-Procedure Calls (JSON-RPC 2.0) supported by the service.

To quickly test your LdapAuth service you can make a few requests using the JSON-RPC 2.0 Shell (included in the downloaded ZIP). It behaves pretty much like a regular Windows or Unix CLI, but instead for issuing OS commands it interacts with a remote JSON-RPC server.

Start the JSON-RPC 2.0 Shell like this, specifying the LdapAuth URL:

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

This will open a JSON-RPC 2.0 shell session to the specified LdapAuth HTTP URL. The --auto-id 0 option turns on automatic appending of request IDs to outgoing JSON-RPC requests.

JSON-RPC 2.0 Shell, version 1.12 (r)

Hints:
        1. Example request with positional parameters and an ID of zero:
                JSON-RPC 2.0 > addNumbers [10,20] 0
        2. Example request with named parameters and an ID of one:
                JSON-RPC 2.0 > divideNumbers {"dividend":27,"divisor":3} 1
        3. Example notification with no parameters:
                JSON-RPC 2.0 > notifyIdleState
        4. To avoid typing request IDs repeatedly invoke the shell with
           the -a/--auto-id option and specify a default ID value
        5. Press [Ctrl] + [C] to exit
JSON-RPC 2.0 >

Here is an example session demonstrating three of the LdapAuth web calls ( assuming an LdapAuth configuration pointing to the sample LDAP directory included with the package):

  • ws.getName To check that the web service is indeed LdapAuth.

  • user.auth To authenticate user alice.

  • user.authGet To authenticate alice and retrieve selected attributes from her directory account on success.

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" ] }

The JSON-RPC shell manual provides further information about its command line arguments and use.

6. Questions?

Get in touch with our support should you need help with the LdapAuth web API and its integration into your web application.