First look at JsonSSO

Earlier in August I began work on JsonSSO, a web service that provides single sign-on and session management. It naturally complements Json2Ldap, another product of mine which provides web-friendly JSON-RPC access to LDAP v3 compatible directories such as OpenLDAP, MS AD and Novell eDirectory.

The recent years we saw a proliferation of single sign-on (SSO) solutions. While the underlying concept of SSO is relatively simple, the IT context (participating apps, authentication methods, back-ends, platforms, policy, etc.) can vary significantly, which has prompted the development of so many implementations.

JsonSSO has three defining features:

  1. User authentication is done against a back-end LDAP directory via Json2Ldap.
  2. Once a user session is established, participating web clients may be given an open LDAP connection (by means of Json2Ldap) bound as the currently logged-in user. This connection allows web clients convenient and flexible access to user details such as user ID, name, email, photo, application preferences, etc.
  3. An internal database records the details of all active and expired user sessions. It can be queried for audit and management purposes via a JSON-RPC interface.

For JsonSSO to be easy to understand and work with I intend to stick to these three main features. Diversions, such as adding DB-based authentication, will be avoided. I want to have JsonSSO as web-friendly as possible, keeping all incoming (from clients) and outgoing (to back-end) connections in the form of HTTP.

Here is a preliminary overview of the JsonSSO API and its configuration settings. These may change somewhat by the time JsonSSO is officially released (Q4 2010).


  • sso.login Initial login with an authenticating ID (username, email, etc.) and password. Returns a new session identifier (SID) which can be passed between the participating web clients and apps.
  • sso.logout Closes a user session. Can be invoked by any of the participating web clients and apps that holding the corresponding SID.
  • sso.getUserID By passing a valid SID, clients can get the user’s system/org-wide ID.
  • sso.getUserDN By passing a valid SID, clients can get the distinct name (DN) of the user, i.e. their directory record.
  • sso.getJson2LdapURL Returns the URL of the Json2Ldap web service.
  • sso.getAnonymousLdapConnection Returns an anonymous LDAP connection (via Json2Ldap) to the back-end directory (if permitted by config).
  • sso.getBoundLdapConnection Returns an LDAP connection (via Json2Ldap) bound as the currently logged-in user (if permitted by config and the web client/app has authorisation).
  • sso.refresh Allows clients/apps to extend a user session by presenting its SID, otherwise it would eventually expire after a preconfigured idle time.
  • sso.getSessionSettings Returns the max idle time, max duration and other settings for a session represented by a given SID.
  • sso.registerLogoutCallback Allows participating web apps to receive a notification that the user has logged out and the session has ended.
  • sso.unregisterLogoutCallback Allows to cancel a previously registered logout notification.
  • sso.listRegisteredCallbacks Lists all web apps that have requested to receive a logout notification.
  • sso.listSessions Lists the details of current or expired sessions. Regular users can only access their own session history. Administrators have full access.
  • ws.getName Returns the web service name.
  • ws.getVersion Returns the web service version.
  • ws.getTime Returns the local web service time.

JsonSSO configuration parameters

This set of parameters governs web client/app access to the JsonSSO service:

  • jsonsso.clients.requireHttps
  • jsonsso.clients.returnAnonymousLdapConnection
  • jsonsso.clients.returnBoundLdapConnection
  • jsonsso.clients.allowLogoutCallbacks

User session limits:

  • jsonsso.sessions.maxTime
  • jsonsso.sessions.maxIdleTime
  • jsonsso.sessions.quotaPerUser
  • jsonsso.sessions.onQuotaExhaustion

Specifies the Json2Ldap URL through which the back-end LDAP directory will be accessed:

  • jsonsso.json2ldap.url
  • jsonsso.json2ldap.trustSelfSignedCerts

Specifies the server details of the back-end LDAP directory. If the useDefault parameter is true JsonSSO will use the default LDAP server for the configured Json2Ldap gateway/proxy.

  • jsonsso.ldapServer.useDefault
  • jsonsso.ldapServer.port
  • jsonsso.ldapServer.timeout
  • jsonsso.ldapServer.trustSelfSignedCerts

The uidAttribute parameter specifies the name of the LDAP attribute that holds the system/org-wide user IDs (typically userid but may be something else). If set, the groupDn parameter governs which users are allowed to login via JsonSSO.

  • jsonsso.users.uidAttribute
  • jsonsso.users.groupDn

This set of parameters determines how to derive the user directory record (DN) from the username or email entered at login:

  • jsonsso.dnResolution.method
  • jsonsso.dnResolution.dnTemplate
  • jsonsso.dnResolution.searchFilter
  • jsonsso.dnResolution.searchBaseDn
  • jsonsso.dnResolution.searchUserDn
  • jsonsso.dnResolution.searchUserPassword

This set of parameters determine which users have admin access to the session logs:

  • jsonsso.admin.dn
  • jsonsso.admin.groupDn