RESTful API for legacy SunSSO

For various reasons, many organizations (have to) use legacy applications. That is simply a fact we need to cope with while creating integration solutions. One of our customers use really old SunSSO, which was released about ten years ago, and use it for authenticating users. This particular version of SunSSO doesn’t have any simple API for external applications. It has only the SOAP service which cannot be used, e.g. for session token validation. Because we needed to validate sessions from other applications, we wrote ourselves a simple RESTful API.

Using servlets as REST providers

SunSSO was open-sourced in 2005 as OpenSSO but, later after acquisition, Oracle  removed the source code from the download sites. Company called ForgeRock created a fork of OpenSSO and develops the product under the name OpenAM. OpenAM comes with a nice pack of REST services. Their specification was a base specification for our servlet REST interface. The specification considered here is from OpenAM 10. In version 11, ForgeRock marked it as deprecated and moved to more convenient JSON format. Specification we used can be found here.

For accessing functionality of the access manager itself, we need to deploy servlets into the same application context. This will ensure that requests can be forwarded into the AM’s classes. The principle is that the servlet translates client requests into objects and then forwards those objects in standard manner into the access manager.

Example: Session validation

There comes a simple example on how to write a session validation servlet by yourself. First, we set up the development environment – standard J2SE project is perfectly sufficient.

Now we have to add the development dependencies: am_sdk.jar, am_services.jar, servlet.jar. All those can be found in your existing SunSSO installation. Just copy them over and update classpath of the newly created project. Also, do not forget to set appropriate JVM version (1.5 in most cases).

The validation servlet could look like this:

public class IsTokenValidServlet extends HttpServlet {

 public static final String TOKENID_GET_PARAM_NAME = "tokenid";


 public void doGet(HttpServletRequest request, HttpServletResponse response) {
 ServletOutputStream out = null;
 try {
   out = response.getOutputStream();
   String tokenid = request.getParameter(TOKENID_GET_PARAM_NAME);

   if (tokenid == null || tokenid.equals("")) {
   } else {
     SSOTokenManager manager = SSOTokenManager.getInstance();
     SSOToken token = manager.createSSOToken(tokenid);

     if (manager.isValidToken(token)) {
     } else {

 } catch (Exception e) {

Example: Servlet deployment

Suppose we created the IsTokenValidServlet as shown in the previous section. Now we need to deploy it.

First, package the compiled class into jar archive (lets call it RESTservlet.jar). Copy this jar into the directory where other SunSSO jars are located. Open the server.xml file of the AM server and add the /path/to/RESTservlet.jar into the classpath so the server can find our class.

Second, register the servlet into the AM namespace. Open the web.xml of the AM application and add those lines:

   <description>REST-like SSO token validation</description>

The final thing you need to do is to restart the application container. After the restart, you should be able to access token validation servlet in the path:



As we have shown, it is not so hard to write functioning REST-like API even for old SunSSO software but we feel that many people could actually use it. That is why we chose to make sources publicly available. You can clone the git repository from the:

We use self-signed certificate. To turn off certificate check temporarily, issue clone in the following form:

GIT_SSL_NO_VERIFY=true git clone

In the repository you can find the existing REST servlets source codes. Unfortunately – due to licensing – we couldn’t add the jar dependencies. It probably does not matter since those of you who will need to use these servlets, will probably have access to an instance of SunSSO.

Any feedback, patches or comments are greatly appreciated. If you have questions you can also contact author by email:

Leave a Reply