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 !