Before I start yapping on, I have to state that ForgeRock documentation is often very useful. The company certainly makes an effort to ensure the document reflects to the precise version that you're using. this post however is the first document that has preempted assumptions and 'gray areas' of knowledge that would allow you to implement the example within your forgeRock environment. Furthermore, there are hints that the example was used (and is still stewed) with OpenSSO. It's probable that you've reached this website in the failed event of trying to integrate your OpenAM spring security integration example. Just to ensure there's an understanding on what you're doing here, you're integrating the web application that uses the spring security framework so you can authenticate directly with OpenAM.

This basically means that you're NOT installing a web agent (though it is possible to integrate your web agent (which eventually creates your session to then integrate it with your SDK), which you may typically perform when implementing your web app into your business solution. Instead, you're tightly integrating the spring application directly with OpenAM.

Eventually, this is a 'spring' application, so your application uses an applicationContext.xml file. Within that file, it will typically identify the process of authentication, which is performed by a 'provider'. ForgeRock has it's own 'provider' that the application can use to then control the context.

So bottom line, your spring application uses the ForgeRock provider to authenticate and extract data from the user. This ForgeRock Provider (aka com.sun.identity.provider.springsecurity.OpenSSOAuthenticationProvider, which you can see within the ac-security.xml file) 'chats' directly to OpenAM and builds a context object instance for your application to use. Dont worry about the provider for now, the example application that's available has already setup the provider for you!

Just to avoid differential environments, I have identified the focal versions of my environment. For my single virtual instance, I'm running two tomcat 8.0.30 containers. This isn't the latest version (as of this blog there's tomcat 9 out) though you can download the exact version here

I setup two containers because if the application fails, the tomcat startup fails. Therefore I have my 'working' applications (including OpenAM 11.0.0) on one server and my Spring application running on my other tomcat container.

My JAVA_HOME is JDK 1.7.0_79. Initially my VM instance was configured with 1.8.0_65 though I discovered that OpenAM would hang during installation (This was because Java 8 does not with OpenAM 11.0.0)

I've also setup the lines within my .bash_profile file:
CATALINA_OPTS=-Dcom.iplanet.am.cookie.name=iPlanetDirectoryPro -Dcom.sun.identity.federation.fedCookieName=fedCookie $CATALINA_OPTS
export CATALINA_OPTS

My flavor of choice is Eclipse. It's not mandatory however it simplifies the svn repository extraction as well as the maven packaging. You need to setup your SVN software AND the connectors. This link, Installation Instructions, has a video that provides a great understanding on how to install SVN as well as the connectors.

Once that's been setup, right-click within the SVN Repositories and click 'check out as Maven Project...'. Add the example URL. If SVN requests for the authentication details, then you need to enter your forgeRock backstage credentials. If you don't have credentials, access the ForgeRock Backstage page and setup an account.Once you've done that, you should have the project duplicated within your local environment to play with (see picture)

As soon as you've downloaded the maven project, maven will instantly acknowledge which dependent jar files required, which of course is highlighted within your pom.xml file.

Nothing needs to be altered to the pom.xml, you simply need to ensure that your 'maven dependencies' get populated automatically within your project (as seen in the screenshot). This can be painful and mind-numbing if you're setting behind a proxy or have FW/anti-virus issues

Within the ForgeRock page, it does state that 'you will need to configure AMConfig.properties according to your settings' though it doesn't state what exactly you need to alter. Don't worry though, here are all the changes that are required to be altered within your AMConfig.properties file to match your environment. Go into your properties file and make the changes.
Once you done all the changes, you can then attempt to run the package command within eclipse. Right-click on the project and select 'run configurations...'. Once you've done that, enter in 'package' within the goals textfield (see screenshot) and click run.

Your response should be something like this and a examplewar-0.2.war should be created.

Bingo, a created 'war' file! All plain sailing from now on! Of course move this war file into the tomcat/webapps directory and startup your tomcat instance. If you kept the war file the default name, you can then access the similar URL http://server1.drdomain.com:8081/examplewar-0.2 (NOTE: the server name and port number may differ in your environment). It should then direct you to the com.sun.identity.loginurl value, which this should be your ForgeRock login screen then you'll see the application pages

If you managed to get the application to redirect to the forgeRock SSO login screen and authenticate with the 'amadmin' credentials and also see the iPlanetPro token within your browser, but you still get the forgerock examplewar-0.2/faces/loginfailure.jsp

Change your com.iplanet.am.cookie.encode to from 'true' to 'false'. It's been 'changed by Warren' though I have no idea who Warren is or why he's even changed this though this resolved my issue. If you managed to get the application to redirect to the forgeRock SSO login screen (so far so good) and you get the iPlanet token by using the 'amadmin' (or any other) credentials. Once you authenticate though, you still land on forgerock examplewar-0.2/faces/loginfailure.jsp Firstly, as stated within the original forgeRock blog, that you're setting the CATALINA_OPTS is declared either within your .bash_profile or within the setenv.sh file (or within your bash_profile if you're riding with Unix) , the 'setenv.sh' file SHOULD reside within your bin directory of your tomcat container. If the setenv.sh file is not located within the bin directory, simply create a file (as it doesn't come OOTB and add the following line into the file

export CATALINA_OPTS="-Dcom.iplanet.am.cookie.name=iPlanetDirectoryPro -Dcom.sun.identity.federation.fedCookieName=fedCookie $CATALINA_OPTS"
To further investigate the issue, check out the debug directory is within the folder, '/tmp/openssoclient' (if you left it as default within your config file. I also noticed a redirect (TOO_MANY_REDIRECTS) issue when it was unable to locate the ERROR: Error creating SSOToken, com.iplanet.sso.SSOException: Invalid session ID. which then ultimately returns the Caused by: com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction: FATAL ERROR: Cannot obtain Application SSO token error within the thread stack. My recommendation is to review blog, Unable to obtain Application SSO token - openam, which I believe will provide you further insight on the troubleshooting.

About the author