Web Services Security with OpenSSO Security Token Service (STS)

I recently experimented with OpenSSO Secure Token Service, one of the rare component Oracle will migrate from Sun’s Identity Management Suite to Oracle’s IAM Suite.

An Open Source implementation is also available from ForeRock’s OpenAM.

To summarize, a Secure Token Service is a third-party broker where Web Services clients can authenticate and receive a security token to be sent to a Web Service Provider.  The Web Service Provider will, in turn, validate the token and to evaluate authentication and authorization decisions.

The best STS description / tutorial I found on the web is on a deprecated page of Microsoft’s MSDN.  If you don’t know about STS, I highly recommend to read this serie of articles.

After installing / setting up OpenSSO / OpenAM, you will be ready to configure the STS part.

There are three approaches to interact with STS Server

Approach #1 – STS’s WSDL definition

This is the platform agnostic approach.  Just rely on STS’s WSDL definition to generate whatever client code you will need.

Unfortunately, on Java SE 6, this approach fails because of incompatibilities in OpenSSO’s STS WSDL definition and JAX-WS.

ForgeRock’s community is tracking this issue under Bug ID 287 and Bug ID 306

Stay tuned on ForgeRock’s JIRA for more details on this approach.

Approach #2 : Using JAX-RPC and JSR 196 provider

JSR 196 is a SPI specification allowing to hook a filter inside a container.  This filter will be invoked for all incoming and outgoing JAX RPC call, allowing it to be used for logging or security purposes for example.

OpenSSO and OpenAM do provide a JSR 196 provider for web service authentication (JSR 196) and authorization (JSR 115).  This provider is able to work with an STS provider.  The provider is available as part of openssowssprovider.jar JAR file.

While a little cumbersome to configure, this approach is working out of the box.  As long as you strictly follow the documentation.  These troubleshooting steps will probably be useful as well.

However, this approach has a major drawback : it is JAX RPC based, i.e. quite old, now that the (Java) world has embraced JAX WS.  In other words, Oracle only supports this when the web service provider and the web service consumer are deployed into a GlassFish v2 instance.

So, if you want to use JAX WS, you will require a little more work.

Approach #3 – JAX WS

JAX-WS also provides hooks to intercept outgoing and incoming SOAP requests.  These hooks are named “Handler“.

The good news about Handlers is that they are web-app specific, unlike JAX-RPC JSR 196 provider which are installed at container level; hence for all your web applications.

You can think of an Handler as a Servlet Filter, dedicated to web service calls.  They can be part of a web app, to protect web services providers, or stand alone client, to protect web service consumers.  IBM has a very good documentation about using Handlers with JAX WS web services.

To test OpenSSO / OpenAM STS service with JAX WS handlers, I suggest you to read this tutorial.

All in all, this is an excellent step by step article, covering deployment in Tomcat, GlassFish and Websphere.

Unfortunately, you will soon realize that these step by step instructions are not working.

Problem #1 : Oracle removed the download link to openssowssagents.jar file.  Yes you read it right.  As of today, there is no binary distribution for the JAX WS Handlers and WSS Agents.  The JAR file is only available from ForgeRock.

Problem #2 : JAX-WS ClientHandler and ServerHandler are not included in openssowssagents.jar file.  So even, if you are downloading ForgeRock’s JAR file, you won’t get these two JAX WS handlers.

So the only solution is to download the source code and built it yourselves.  Building OpenSSO / OpenAM is not an easy task.  This product has many dependencies and historical (legacy) branches.  Anyway, your build will not be supported by Oracle nor ForgeRock.  For your convenience, here is a openssowssagents.jar file with the JAX WS classes included.

Should you have a valid support contract with Oracle and/or ForgeRock, do not hesitate to open a support case and see what / if /how they will handle this situation.

Enjoy !

, , , , , , , , , ,

  1. #1 by Mike on 04/01/2011 - 20:07

    The only opensso download I was able to find is the oracle opensso sts.


    All the links to opensso 8 seemed to require a support contract from oracle.

  2. #2 by sst on 04/01/2011 - 20:28

    Correct. Recent builds of OpenSSO are provided by http://www.ForgeRock.com

  3. #3 by Mike on 05/01/2011 - 07:12

    Assuming you get oracle open sso sts setup in glassfish can you then use approach 3 against this sts?

    The oracle open sso sts seems to be quite different from all the tutorial information that is out there. For instance the only agent available is the web service provider where as the tutorial you reference shows a screenshot of web service client, sts client, etc in this image:


    Or can I somehow put the openssowssagents.jar into my sts?

    Thank you!

  4. #4 by Mike on 08/01/2011 - 01:17

    Looks like openam951 has all the same agents as displayed in the tutorial. Hopefully your comment only meant that if you didn’t have openssowsagents.jar that you need to build.

  5. #5 by sst on 09/01/2011 - 10:41


    That’s the point of my blog post. The JAX WS agent is not provided as a binary nor from Oracle, nor from ForgeRock. Should you have a valid support contract with any of these two companies, I strongly suggest you to open a support call and ask for it. (BTW – I am interested by Oracle’s response…)

    Worst case, you can either build OpenAM from ForgeRock’s source tree or develop your own JAX WS agent, as this is extremely simple (you can inspire yourself from ForgeRock’s source code) – probably less than 50 lines of code.

  6. #6 by Mike on 11/01/2011 - 22:44

    I finally got my openam stock quote up and running. I didn’t need to build openam though.

    I just grabbed the openssowsprovider.zip file from:


    and replaced the contents of the lib directory with the matching updated libraries from the
    opensso.war that is included in the openam951 snapshot zip file.

  7. #7 by Glen on 22/02/2011 - 00:45

    The first problem you listed was “As of today, there is no binary distribution [openssowssagents.jar] for the JAX WS Handlers and WSS Agents. The JAR file is only available from ForgeRock.”

    But that FR download page doesn’t have openssowssagents.jar either. What instead should I be downloading from the ForgeRock page? (I know I’ll still be missing the two classes you listed in Problem #2 but want to make sure I have the rest of the library correct.) Thanks!

  8. #8 by sst on 22/02/2011 - 07:51

    You should download “WSS Agents” available at the bottom of this page http://www.forgerock.com/downloads.html

  9. #9 by Glen on 08/03/2011 - 03:06

    You should download “WSS Agents” available at the bottom of this page http://www.forgerock.com/downloads.html

    Thanks, but despite the “Agents” heading, that ZIP looks to be the *providers* (JSR-196 for Glassfish, not for Tomcat use.) openssowss*providers*.zip. Googling elsewhere, it apparently has been renamed by OpenAM to wssagents.zip, but even that’s unavailable now — it looks like I’ll have to manually build from (non-Mavenized, alas) source.

  10. #10 by sst on 08/03/2011 - 07:09

    This is possible – I didnt check recently.
    You should ask the question on OpenAM mailing list. fR people to answer very quickly most of the time
    Good Luck !

(will not be published)