JsonSSO :: Quick Start

Download and unzip

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

Deploy

The JsonSSO web service classes, required libraries and configuration are packaged in a standard WAR file called

jsonsso.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/jsonsso/ and start the JsonSSO service.

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

Verify

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

http://localhost:8080/jsonsso/

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

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

Use HTTP POST to submit your JSON-RPC 2.0 request

Web service: JsonSSO, version 1.2 (2011-12-27)
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 the standard web.xml service descriptor file which is located in the JsonSSO deployment directory tree on the web server:

webapps/jsonsso/WEB-INF/web.xml

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

The LDAP attribute that identifies users system / organisation-wide.
The web service access policy (client IP whitelist, whether HTTPS is mandatory, etc).
The session settings, such as max idle time.
The Json2Ldap URL and the LDAP server details (if one needs to be explicitly defined).
The service account DN and password for LDAP search operations.
The parameters for resolving the user directory entries from the login usernames.

Refer to the configuration manual for a detailed description of how to set up JsonSSO.

Remember to restart your web service or server after updating the JsonSSO configuration!

Usage

The JSON remote procedure calls (RPC) served by JsonSSO 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 JsonSSO 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 JsonSSO URL:

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

This will open a shell session to the specified HTTP URL where the JsonSSO 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 JsonSSO service and its version and then to login a user (the input commands are in bold):

JSON-RPC 2.0 > ws.getName
JsonSSO


JSON-RPC 2.0 > ws.getVersion
1.2 (2011-12-27)


JSON-RPC 2.0 > sso.login { "user" : "alice", "password" : "s3cr3t" }
{ "SID"         : "e38ae25e-9d07-42f3-b64f-e852fe37c307",
  "userID"      : "alice",
  "userDN"      : "uid=alice,ou=People,dc=wonderland,dc=com",
  "started"     : "2011-04-27T11:21:16+01:00",
  "refreshed"   : "2011-04-27T11:21:16+01:00",
  "maxTime"     : 1440,
  "maxIdleTime" : 15,
  "Json2Ldap"   : { "URL" : "http://localhost:8080/json2ldap/",
                    "CID" : "2a954175-afa0-4bb9-b966-be0ef6c7b7fc" } }


JSON-RPC 2.0 > sso.getUserID { "SID" : "e38ae25e-9d07-42f3-b64f-e852fe37c307" }
alice


JSON-RPC 2.0 > sso.logout { "SID" : "e38ae25e-9d07-42f3-b64f-e852fe37c307" }
null

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