It’s been a couple of months since Part 1, so time to put pen to paper. I’ll post Part 3 up in the next few days. Sorry for those who’ve had to wait…

In the previous OpenAM/AD FS  post we covered the installation of OpenAM . In this post we’ll concentrate on preparing the platforms for identity federation. One thing I won’t be doing is covering the actual installation of AD FS 2.0. That’s well documented elsewhere. I’ll assume that you have a working AD FS 2.0 configuration.

We’ll begin on the AD FS 2.0 side by creating two custom claims descriptions. If you read the previous post concerning AD FS 2.0 Rollup 1: Client Access Policy Support for O365, then you may recognize this process.  From the AD FS 2.0 MMC snapin and service panel, I’ve create two custom claims descriptions:

• http://schemas.auth360.net/2012/01/requestcontext/claims/x-am-uid for User ID

• http://schemas.auth360.net/2012/01/requestcontext/claims/x-am-mail for E-Mail Address

It’s important to stress that the URLs are not real ones. They are there for reference and administrative purposes and:

• they are to aid managing our rulesets and are used in the federation metadata exchange between OpenAM and AD FS 2.0.

• using short attribute names for claims type descriptions, e.g. mail, uid etc.,  while possible, can causes headaches, particular with multiple claims providers, as we’re dealing with common attributes / descriptions. A provider-specific namespace helps avoid this confusion;

• we want to create a unique association between the entities concerned: OpenAM and AD FS 2.0…

We’ll reference these claim descriptions on the OpenAM side later in the setup process. We create them now so that when we register the remote service provider in OpenAM, the relevant metadata is there.

Let’s return to OpenAM …… for federation purposes, we will need to configure a signing key  to be used by OpenAM . This key is then used to sign metadata. This can be quite a confusing process, so as ever, test test… OpenAM comes with a default test (signing) key that is common to all installations and, as a result, use of this test key should not be considered secure. We’ll create a new test signing certificate and import this into the Java keystore that OpenAM uses.

Note: This is a different Java keystore (JKS) to the one referred in the previous article and used by the web container, Tomcat.

Login to the OpenAM console as amadmin, click on the Configuration tab, then on Servers and Sites and then click on the OpenAM server URL. On the next screen, select the Security tab and scroll down

Based on settings from Part 1, the %BASE_DIR% variable that we set in the graphic above alludes to C:/OpenAM. The current certificate alias is set to test, meaning that the server is currently using the default test certificate for token signing. We need to change this. First we’ll need to turn off inheritance so that we can manually change the certificate alias value. This is accomplished by clicking on the Inheritance Settings  button in the top left corner.

On the subsequent screen, select the Uncheck the Certificate Alias option.

This now enables us to change the Certificate Alias to be used for Token signing from the Test certificate to something else.

In this example, we’ll switch the alias and call it openam token signing cert..

OpenAM needs to reference keys and certificates for the hosted server instance. This includes a key pair for the host running OpenAM in a JKS format. Under the JDK in the BIN folder is the Java keytool file. Using this tool we’ll now create a new Java Keystore (JKS) to replace the default one.

The certificate properties (Name, OU, City, State, Postcode/ZIP, X500 code etc.) will be asked for when the tool runs. Note that we can also create a keystore in tools such as Portecle or Keytool UI if we so choose. Whichever route you select, both will require the keystore to be protected with a password to access the store and also a password for individual keys. These passwords must be encoded with OpenAM, and the information therein stored in the files .keypass and .storepass (these files live in the OpenAM configuration directory).

We can encode the password a couple of ways.

Option 1: Encoding Servlet

There’s an encoding servlet at https://idp.mydomain.com/openam/encode.jsp  as well as command-line tools. This encoding servlet allows for a quick and simple way to encode a password for the .keypass and .storepass files. For example, let’s use the example password of fubarfubar

Click on the Encode button.

Cut and paste the encrypted password string from the webpage into a text file, e.g. MYPASSWORD.TXT. If you’d prefer not to use the ENCODE.JSP option, read on….

Option 2 : OpenAM SSO Admin Tools

Download the OpenAM tools from the ForgeRock website and extract them into a folder (e.g. C:\Tools).

NOTE: These tools can be used after we first set our JAVA_HOME environment variable.

In the example below, SETUP is being run from the tools folder, and when queried for I’ve provided the configuration path information for the OpenAM server, Debug and Log directories.

Once the tools are installed, I’d recommend adding the BIN folder to the PATH environment variable. It’s useful to be able to call them from other locations when performing administration via the command-line.

With the tools setup we can also call the ampassword utility to generate an encoded sequence. Using the same example as the GUI, I first created a file with the password fubarfubar in it and then call the encode parameter.

C:\temp>type test.txt
fubarfubar
C:\temp>ampassword -e test.txt
AQICyRJQ1CNPI3GMU0vBz2oq3IW8xcKf31eG

The encoded text can be cut and pasted into notepad and then saved as .keypass and .storepass. in the OpenAM configuration folder.

1. Drop to the OpenAM configuration folder (C:\OpenAM\OpenAM)
2. Create a folder called BACKUP and copy the original .keypass and .storepass and  keystore.jks into this BACKUP folder.
3. Copy the JKS file (keystore.jks) created in C:\TEMP earlier to the configuration folder, overwriting the existing JKS
4. Copy MYPASSWORD.TXT to .keypass and .storepass overwriting the default files.
5. Restart the Apache Tomcat service.

We can validate whether the signing key is defined correctly by selecting the Create Hosted Identity Provider option on the Common Tasks screen.

On the metadata screen, select the Signing Key dropdown box and if the token signing cert appears (no errors), we’re good…..

Once we have a proper token signing certificate, we can start setting up OpenAM as an Identity Provider (IdP). OpenAM and AD FS can be linked up in a couple of ways via:

• SAML 2.0

• WS-Federation

In this example, we’ll use OpenAM as a SAML 2 Identity Provider (IdP) and AD FS 2.0 as a SAML 2.0 Service Provider (SP). From the metadata screen previously, let’s fill in the necessary details:

We need to create a Circle of Trust (COT). A circle of trust is a collection of Identity and Service Providers within OpenAM that engage in identity federation.  It becomes an authentication domain shared between partners, typically one or more service providers and an identity provider, where the parties can communicate in a secure and seamless manner. We can create a circle of trust (COT) manually, or, as in the above example,  during the IdP creation process.

I’ve selected the signing key from earlier, entered the URL for my Identity Provider (IdP) and created a new circle of trust (COT) called ADFS2. In this case, we will have a COT between a SAML 2.0 Identity Provider (OpenAM) and a SAML 2.0 Service Provider (AD FS 2.0).

Click on the Register a Remote Server Provider link.

On the ensuing screen, change the radio button to File when asked for where the metadata file resides. To make the metadata from AD FS understandable to OpenAM we need to trim the information provided by its federation service, so that we retain only the entity identity and descriptor information within the federation metadata XML that is relevant to SAML 2.0 Service Provider (SP) descriptors.  In other words, anything with WS-Trust material in needs to go….

To do this, obtain a copy of the federation metadata file by pointing to the AD FS metadata, e.g:

https://sts.mydomain.com/FederationMetadata/2007-06/FederationMetadata.xml

1. Download the XML document and save it to file on your desktop / workspace.
2. Create a copy of the file (let’s call it SPDATA.XML)
3. Open SPDATA.XML with an XML Editor (or Notepad if you’re feeling brave)
4. Remove the section beginning <ds:Signature .. ending at </RoleDescriptor>, i.e. all XML tags between EntityDescriptorID and SPSSODescriptor.
5. Keep the <SPSSODescriptor> </SPSSODescriptor> section. 
6. Remove  the <IDPSSODescriptor> </IDPSSODescriptor> section.
7. Keep the remainder of the remaining metadata to end-of-file.
8. Save the SPDATA.XML file
9. Check that the file is not corrupted by opening the XML file via IE.

The SPDATA.XML file can now be uploaded to OpenAM

Click the Upload button to upload the file.

The file should then upload successfully, otherwise it’s likely a formatting error in the XML file. in which case, try opening it in a browser and see whether you get an error about a corrupt / incorrectly formatted XML file.  Repeat and rinse ……..

Next up, the OpenAM Identity Provider configuration and AD FS 2.0 Service Provider …..