OpenAM, previously OpenSSO, is a commercial grade open source offering from Forgerock (www.forgerock.com). It provides conventional access management capability using agents, as well as federation and web services single sign-on (SSO). In the coming posts we’ll look at integrating OpenAM with Active Directory Federation Services using federated identities with SAML 2.0. Specifically, we’ll look at using OpenAM as a SAML 2.0 Identity Provider (IdP) and AD FS 2.0 as a SAML 2.0 Service Provider (SP). This is a fairly common configuration for organizations that have already deployed OpenAM and now need to integrate their access management product with the Microsoft claims aware application landscape.

OpenAM is a Java-based web archive (WAR) application, so we’ll need to install both a Java SDK and a Java servlet web container on which it can run. I’m using the Oracle 1.6.0.x JDK for Windows (x64) and Apache Tomcat 6.0.x  as my web container in this example, although platforms such as Glassfish, JBoss, Websphere, Weblogic are eminently useable.

For expediency, Windows is being used here as the testing platform.

Apache Tomcat 6.0.x Configuration

This is a quick walk-thru and (relatively) barebones explanation of the Tomcat server configuration.  If you’re unfamiliar with Tomcat then have a look at the Apache site wiki (http://wiki.apache.org/tomcat/FrontPage).

In this example, the x64 version of Tomcat 6.x is being installed under Windows 2008 R2. Once installation is complete, run the service.bat file from the BIN folder to install Tomcat as a service.

Usage: service.bat install/remove [service_name]

C:\apache-tomcat-6.0.xx\bin>service install
Installing the service ‘Tomcat6’ …
Using CATALINA_HOME:    “C:\apache-tomcat-6.0.xx”
Using CATALINA_BASE:    “C:\apache-tomcat-6.0.xx”
Using JAVA_HOME:        “”
Using JVM:              “auto”
The service ‘Tomcat6’ has been installed.

One thing that does need modifying is the amount of memory available to the Java Heap space and the PermGen space. Normally this is done through the CATALINA.SH file. However,  since we’re running Tomcat under Windows as a service, this can be changed using the TOMCAT6.EXE  file in the BIN folder.

tomcat6 //US//Tomcat6 –JvmMx 1256 ++JvmOptions=”-XX:MaxPermSize=256m”

The label //US//Tomcat6 updates the existing server parameter. Here we’re increasing the maximum heap size to 1256.  Since AD FS 2.0 is involved, the Tomcat web container also needs to be using SSL. We’ll need to customize the SERVER.XML within Tomcat to support the use of HTTPS with a certificate. In the example below we’re using a wildcard certificate (keyAlias)

<Connector port=”443″
protocol=”org.apache.coyote.http11.Http11Protocol”
SSLEnabled=”true”
maxThreads=”200″
scheme=”https”
secure=”true”
keystorefile=”C:/.keystore”
keystorePass=”changeit”
keyAlias=”*.mydomain.com”
clientAuth=”false”
sslProtocol=”TLS” />

The keystorefile directive uses Unix paths, although drive letter literals are accepted.  Again, this can be a bit overwhelming at first so a read of the Tomcat SSL Configuration HOW-TO may be advised if SSL/Tomcat is something new.

http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html

Tomcat, in this configuration, is using a Java keystore (JKS) to store digital certificates, within which will reside our wildcard certificate for web server authentication. Some form of keytool utility to import the certificate with private key (PKCS#12 file) is required. There are various Java keytool progs out there. Here we’re using Portecle, available off SourceForge:

http://portecle.sourceforge.net/

Portecle can also be used to import intermediate certificates into the core Java certificate store, should your third-party certificate provider have an extended certificate chain. This file can be found under the Java program path /jre/lib/security/cacerts

OpenAM Configuration

The latest OpenAM files are available from the Forgerock site. The OpenAM ZIP file contains a deployable-war directory containing an opensso.war file. This file can be dropped under the WEBAPPS folder of the Tomcat application server. Here we’ve renamed the file to openam.war in the process of copying it over as this becomes the Server URI path for logon. Restarting the Tomcat services will expand and deploy the WAR file. 

OpenAM comes with an embedded LDAP server which can be used simultaneously for storing identities and also as a configure store/repository.  This is a Java-based LDAPv3 compliant open-source directory, formerly known as OpenDS, and delivered by Forgerock under the OpenDJ moniker. We’ll use an embedded configuration store in this example.

1. Create a host record (A) record in your local DNS for the name of the OpenAM server or create a loopback entry in your hosts file under system32/drivers/etc, e.g. 127.0.0.1 idp.mydomain.com.

2. Point your browser to https://idp.mydomain.com/openam. The configuration options wizard will begin. Select Create New Configuration

3. Enter a password for the default administrator user (amAdmin). is the default administrative/super user used for administration of OpenAM.

4. Enter a server URL for OpenAM (e.g. https://idp.mydomain.com:443) and cookie domain (.mydomain.com)

5. Use the embedded (OpenAM) configuration data store.

6. Select OpenAM as the User Data Store (this is a development/test environment). In a production environment, one of the other LDAP user stores should be used.

7. This is a development/test environment, it’s not behind a load-balancer, hence the No selection.

8. Enter a password to be used by OpenAM Policy Agents and click Next.

9. Review the configuration summary and click Create Configuration when ready.

10. OpenAM configuration should now begin.

11. Once setup is complete, reboot the server.

12. Launch a browser and point it the OpenAM instance, e.g. https://idp.mydomain.com/openam. Login with the amadmin account and the password chosen earlier.

13. The common tasks wizard screen will appear.

In the next article: configuring OpenAM and preparing it for identity federation is the subject.

Good luck!!

Mylo