AuthService :: Quick Start

Download and unzip

Extract the downloaded AuthService ZIP package in a suitable folder in your computer.

Deploy

The AuthService classes, library dependencies and configuration are packaged in a standard WAR file called

authservice.war

You need to deploy this WAR package into your Java web server. If you don't have one you can grab a free copy of the popular open-source Apache Tomcat or Jetty servers.

If you're using Apache Tomcat, simply copy the WAR file to the webapps/ directory of your Tomcat installation and restart the server. The server will then automatically extract the content of the WAR package into a directory called webapps/authservice/ and launch an AuthService instance.

Other web servers may have a different WAR deployment procedure, through a web UI or from the command line. This should be a simple and quick thing to do.

Verify

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

http://localhost:8080/authservice/

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

If the AuthService is up and running you should see the following text in your browser:

Use HTTP POST to submit your JSON-RPC 2.0 request

Web service: AuthService, version 2.0 (2012-02-20)
Vendor: Nimbus Directory Services, http://nimbusds.com

This message basically says that the service expects JSON-RPC 2.0 requests received by HTTP POST.

Configure

The configuration is stored in a standard properties file located in the AuthService deployment directory tree on the web server.

webapps/authservice/WEB-INF/authservice.properties

Open this file with your favourite text editor and modify the required properties accordingly, in particular

The web service access policy (client IP whitelist, wheter HTTPS is mandatory, etc).
The LDAP directory hostname and port number.
The parameters for resolving usernames to concrete directory entries (DNs).

Refer to the configuration manual for a detailed description of the AuthService properties.

Remember to restart your web server after updating the AuthService configuration!

Usage

The JSON remote procedure calls (RPC) served by AuthService are described in the web API reference. These can be scripted from web browsers using direct XHR invocation or from any other application with access to the web.

To quickly test your AuthService instance and its JSON-RPC 2.0 interface you can send a few JSON requests using the JSON-RPC 2.0 Shell (included in the download package). It behaves pretty much like a regular Windows or Unix CLI, but instead for issuing OS commands it is used to interact with a remote JSON-RPC server.

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

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

This will open a shell session to the specified HTTP URL where the authentication service is accepting JSON-RPC 2.0 requests. 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, where we enter a few requests to verify the AuthService and its version and then to authenticate the user alice (the input commands are in bold):

JSON-RPC 2.0 > ws.getName
AuthService


JSON-RPC 2.0 > ws.getVersion
2.0 (2012-02-20)


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


JSON-RPC 2.0 > user.get { "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" ] }

Check the fine JSON-RPC shell manual if you need help with its command line arguments and usage.