Nimble directory + auth + SSO services for your {web} and {cloud} apps

Nimbus Directory Services

JsonSSO Web API

JsonSSO has a simple and efficient JSON web interface, in the spirit of NoXML.

Requests and responses comply to JSON-RPC 2.0, the latest version of the protocol for remote procedure calls (RPC) using JSON-encoded messages. JsonSSO requests are submitted by means of HTTP POST.

The following table summarises the JsonSSO web API. Click on a request name to see a detailed explanation of it.

Login and logout » Session information » Session refresh »
Logout callbacks » Administration » Web service information »

Each JSON-RPC 2.0 request consists of the following fields:

Example JSON-RPC 2.0 request:

{
  "method"  : "sso.login",
  "params"  : { "user" : "alice@wonderland.net", "password" : "secret" },
  "id"      : "0001",
  "jsonrpc" : "2.0"
}

1. Login and logout

A web client can sign on a user with the sso.login call. This establishes a new user session until it is explicitly closed with sso.logout or until it expires (see the JsonSSO session configuration parameters).

sso.login

Logs in a user with the specified username and password. Returns a JsonSSO session object on success or an -3000 "Bad username/password" error if the supplied credentials are invalid.

Parameters:

Result:

Examples:

Example request to log in a user with email alice@wonderland.net and password secret:

{ "method"  : "sso.login",
  "params"  : { "user"     : "alice@wonderland.net", 
                "password" : "secret" }
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Response indicating the credentials were valid and a new session was started.

{ "result"  : { "SID"         : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "userID"      : "alice",
                "userDN"      : "uid=alice,ou=people,dc=wonderland,dc=net",
                "started"     : "2011-04-28T15:56:58+01:00",
                "refreshed"   : "2011-04-28T15:56:58+01:00",
                "maxTime"     : 1440,
                "maxIdleTime" : 15,
                "Json2Ldap"   : { "URL" : "http://localhost:8080/json2ldap/",
                                  "CID" : "cb8d823a-9d1c-4fe4-9f1f-de25a1bd19f3" } },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

Note that the session identifier (SID) must be stored by the web client to able to refer to the session in subsequent JsonSSO requests. It may also be passed on to other trusted applications that together form a SSO environment.

Response indicating either the username or the password or both were invalid:

{ "error"   : { "message" : "Bad username/password",
                "code"    : -3000 },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

If for some reason the JsonSSO service couldn't process the request (due to bad configuration, the LDAP server being down or other exception) a JSON-RPC error response is generated. The detailed error message together with the cause will be recorded in the configured log file.

{ "error"   : { "message" : "Internal JsonSSO error",
                "code"    : -3300 },
  "id"      : "0001",
  "jsonrpc" : "2.0" }

sso.logout

Logs out a user and closes their session. Subscribed clients (see sso.addLogoutCallback) will be sent a logout notification.

Parameters:

Result:

Examples:

Example request to log out a user with the specified SID:

{ "method"  : "sso.logout",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0002",
  "jsonrpc" : "2.0" }

Response on success:

{ "result"  : null,
  "id"      : "0002",
  "jsonrpc" : "2.0" }

Response indicating the session has expired in the meantime:

{ "error"   : { "message" : "Invalid/expired session identifier (SID)",
                "code"    : -3010 },
  "id"      : "0002",
  "jsonrpc" : "2.0" }

2. Session information

JsonSSO provides three JSON-RPC methods that allow web clients to retrieve the user's ID and other session related information by simply passing the stored session identifier (SID).

sso.getSession

Retrieves the session details associated with the specified session identifier (SID).

Parameters:

Result:

Examples:

Example request to get the session details that correspond to the SID 5347e9fc-6d20-4183-b3be-67fd35caeb2b:

{ "method"  : "sso.getSession",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0003",
  "jsonrpc" : "2.0" }

A successful response:

{ "result"  : { "SID"         : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "userID"      : "alice",
                "userDN"      : "uid=alice,ou=people,dc=wonderland,dc=net",
                "started"     : "2011-04-28T15:56:58+01:00",
                "refreshed"   : "2011-04-28T15:59:15+01:00",
                "maxTime"     : 1440,
                "maxIdleTime" : 15,
                "Json2Ldap"   : { "URL" : "http://localhost:8080/json2ldap/",
                                 "CID" : "cb8d823a-9d1c-4fe4-9f1f-de25a1bd19f3" } },
  "id"      : "0003",
  "jsonrpc" : "2.0" }

If the specified session identifier (SID) is invalid or the session has expired a -3010 error response is generated:

{ "error"   : { "message" : "Invalid/expired session identifier (SID)",
                "code"    : -3010 },
  "id"      : "0003",
  "jsonrpc" : "2.0" }

sso.getUserID

This method is similar to sso.getSession, however it retrieves only the user ID associated with the specified session.

Parameters:

Result:

Examples:

Example get user ID request:

{ "method"  : "sso.getUserID",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0004",
  "jsonrpc" : "2.0" }

A successful response:

{ "result"  : "alice",
  "id"      : "0004",
  "jsonrpc" : "2.0" }

sso.getUserDN

This method is similar to sso.getSession, however it retrieves only the user DN associated with the specified session.

Parameters:

Result:

Examples:

Example get user DN request:

{ "method"  : "sso.getUserDN",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0005",
  "jsonrpc" : "2.0" }

A successful response:

{ "result"  : "uid=alice,ou=people,dc=wonderland,dc=net",
  "id"      : "0005",
  "jsonrpc" : "2.0" }

3. Session refresh

A session must be periodically refreshed by at least one of the web clients that share it, otherwise it will expire after the configured amount of idle minutes.

sso.refresh

Refreshes the session with the specified session identifier (SID).

Parameters:

Result:

Examples:

Example session refresh request:

{ "method"  : "sso.refresh",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0006",
  "jsonrpc" : "2.0" }

A response with null result indicating success:

{ "result"  : null,
  "id"      : "0006",
  "jsonrpc" : "2.0" }

If the specified session identifier (SID) is invalid or the session has expired a -3010 error response is generated:

{ "error"   : { "message" : "Invalid/expired session identifier (SID)",
                "code"    : -3010 },
  "id"      : "0006",
  "jsonrpc" : "2.0" }

4. Logout callbacks

JsonSSO can be configured to allow web clients sharing a user session to be notified when it finishes due to logout or expiration.

A client can subscribe to be notified by registering a callback request with JsonSSO using a sso.addLogoutCallback request. Callbacks are delivered to an URL specified by the client by means of HTTP GET or POST. The callback message can be of arbitrary content, but typically includes the user ID or some other token that allows the client to identify the user who has logged out.

Here is an example GET logout callback where the identity of the user is encoded in the URL string:

https://my-finance-app.com/notify/logout?uid=012345

And here is an example POST logout callback where a JSON message is passed back to the client:

https://my-finance-app.com/

{
  "method"  : "notify",
  "params"  : { "event" : "logout", "userID" : "012345" },
  "id"      : "0007",
  "jsonrpc" : "2.0"
}

To guard against eavesdropping clients are advised to use logout callbacks that point to a secure HTTPS URLs.

If a callback fails to be delivered this along with the cause is recorded in the JsonSSO log.

Note that the configuration may impose a limit on the number of registered callbacks per session and the size of the POST message.

sso.addLogoutCallback

Registers a logout callback to be delivered upon session logout or expiration.

Parameters:

Result:

Examples:

Example request to register a GET logout callback:

{ "method"  : "sso.addLogoutCallback",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "URL" : "https://my-finance-app.com/notify/logout?uid=012345"}
  "id"      : "0008",
  "jsonrpc" : "2.0" }

If for some reason the callback couldn't be registered an error response is returned:

{ "error"   : { "message" : "Logout callback quota exceeded",
                "code"    : -3033 },
  "id"      : "0008",
  "jsonrpc" : "2.0" }

Other possible callback related errors are -3030 "Logout callbacks not allowed", -3031 "Invalid HTTP URL", -3032 "No message body is allowed with GET callbacks" and -3034 "Logout callback message size exceeded".

sso.removeLogoutCallback

Removes a previously registered logout callback for the specified session and URL.

Parameters:

Result:

If no callback was found for the specified URL a null result is returned.

Examples:

Example request to remove a GET logout callback:

{ "method"  : "sso.removeLogoutCallback",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "URL" : "https://my-finance-app.com/notify/logout?uid=012345" }
  "id"      : "0009",
  "jsonrpc" : "2.0" }

Example response with the removed callback:

{ "result"  : { "URL"     : "https://my-finance-app.com/notify/logout?uid=012345",
                "method"  : "GET",
                "message" : null },
  "id"      : "0009",
  "jsonrpc" : "2.0" }

sso.listLogoutCallbacks

Lists the registered logout callbacks for the specified session.

Parameters:

Result:

Examples:

Example request to list the logout callbacks:

{ "method"  : "sso.listLogoutCallbacks",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" }
  "id"      : "0010",
  "jsonrpc" : "2.0" }

Example response listing two registered callback:

{ "result"  : [ { "URL"     : "https://my-finance-app.com/notify/logout?uid=012345",
                  "method"  : "GET",
                  "message" : null },
		{ "URL"     : "https://my-calendar-app.com/notify/logout?uid=012345",
                  "method"  : "GET",
                  "message" : null } ],
  "id"      : "0010",
  "jsonrpc" : "2.0" }

5. Administration

JsonSSO provides a set of administrative methods to monitor the active sessions as well as to force logout of selected users.

The calling user must have administrative permissions according to the configuration else a -3020 "Permission denied" error will be returned.

sso.listSessions

Lists the sessions for the specified user. The caller must have administrative permissions.

Parameters:

Result:

Examples:

Example request to list the session for user with ID "bob":

{ "method"  : "sso.listSessions",
  "params"  : { "SID"    : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "userID" : "bob" },
  "id"      : "0011",
  "jsonrpc" : "2.0" }

Example response listing two active sessions:

{ "result"  : [ { "SID"         : "07a443bb-6ed1-4c60-a31f-6b2a8e2b4333",
                  "userID"      : "bob",
                  "userDN"      : "uid=bob,ou=people,dc=wonderland,dc=net",
                  "started"     : "2011-04-28T15:56:58+01:00",
                  "refreshed"   : "2011-04-28T15:59:15+01:00",
                  "maxTime"     : 1440,
                  "maxIdleTime" : 15,
                  "Json2Ldap"   : { "URL" : "http://localhost:8080/json2ldap/",
                                    "CID" : "c6297c2f-8778-4d24-a813-278109f81fbc" } },
		{ "SID"         : "083f0d4c-4941-4cb1-93c3-1b1c2960f6cc",
                  "userID"      : "bob",
                  "userDN"      : "uid=bob,ou=people,dc=wonderland,dc=net",
                  "started"     : "2011-04-28T15:56:58+01:00",
                  "refreshed"   : "2011-04-28T15:59:15+01:00",
                  "maxTime"     : 1440,
                  "maxIdleTime" : 15,
                  "Json2Ldap"   : { "URL" : "http://localhost:8080/json2ldap/",
                                    "CID" : "07a443bb-6ed1-4c60-a31f-6b2a8e2b4333" } } ],
  "id"      : "0011",
  "jsonrpc" : "2.0" }

sso.listUsers

Lists the current session users. The caller must have administrative permissions.

Parameters:

Result:

Examples:

Example request to list the current users:

{ "method"  : "sso.listUsers",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" },
  "id"      : "0012",
  "jsonrpc" : "2.0" }

Example response listing three active users:

{ "result"  : [ "alice", "bob", "claire" ],
  "id"      : "0012",
  "jsonrpc" : "2.0" }

sso.sessionCount

Reports the current session count. The caller must have administrative permissions.

Parameters:

Result:

Examples:

Example request to get the session count:

{ "method"  : "sso.sessionCount",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" },
  "id"      : "0013",
  "jsonrpc" : "2.0" }

Example response showing 8 active sessions:

{ "result"  : 8,
  "id"      : "0013",
  "jsonrpc" : "2.0" }

sso.userCount

Reports the current user count. The caller must have administrative permissions.

Parameters:

Result:

Examples:

Example request to get the session count:

{ "method"  : "sso.userCount",
  "params"  : { "SID" : "5347e9fc-6d20-4183-b3be-67fd35caeb2b" },
  "id"      : "0014",
  "jsonrpc" : "2.0" }

Example response showing three active users:

{ "result"  : 3,
  "id"      : "0014",
  "jsonrpc" : "2.0" }

sso.forceLogout

Forces the termination of another user's sessions. The caller must have administrative permissions.

Parameters:

Result:

Examples:

Example request to force the logout of user bob:

{ "method"  : "sso.forceLogout",
  "params"  : { "SID"    : "5347e9fc-6d20-4183-b3be-67fd35caeb2b",
                "userID" : "bob" },
  "id"      : "0015",
  "jsonrpc" : "2.0" }

6. Web service information

JsonSSO also provides three JSON-RPC methods to obtain information about the web service itself. There are the ws.getName and ws.getVersion methods to identify the software and its version, as well as the ws.getTime method that reports the local time at the web server.

ws.getName

Reports the name of web service software.

Parameters: none

Result:

Examples:

Example request message:

{ "method"  : "ws.getName",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "JsonSSO",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ws.getVersion

Reports the version of the web service software.

Parameters: none

Result:

Examples:

Example request message:

{ "method"  : "ws.getVersion",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "1.0 (2011-03-16)",
  "id"      : 1,
  "jsonrpc" : "2.0" }

ws.getTime

Reports the local web service time in ISO 8601 format yyyy-MM-dd'T'HH:mm:ssZZ, for example "2010-03-31T23:59:59+03:00".

Parameters: none

Result:

Examples:

Example request message:

{ "method"  : "ws.getTime",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The response message:

{ "result"  : "2010-11-15T12:14:41+02:00",
  "id"      : 1,
  "jsonrpc" : "2.0" }