unconfigured

The Java Fedlet is basically a lightweight SAML Service Provider (SP) implementation that can be used to add SAML support to existing Java EE applications. Today we are going to try to set up the fedlet sample application with a Shibboleth IdP (available at <a href="http://testshib.org/">testshib.org</a>).

<h4>Preparing the fedlet</h4>
There is two kind of Java fedlet in general: configured and unconfigured. The configured fedlet is what you can generate on the OpenAM admin console, and that will basically preconfigure the fedlet to use the hosted OpenAM IdP instance, and it will also set up the necessary SP settings. The unconfigured fedlet on the other hand is more like starting from scratch (as the name itself suggests :) ) and you have to perform all the configuration steps manually, this is what we are going to use today.

The unconfigured fedlet can be found in the ZIP download for OpenAM, and for OpenAM 11, it should be a file named <i>Fedlet-11.0.0.zip</i>. As a first step let's unzip the file and start to "configure" our fedlet by opening <i>sp.xml-template</i> for edit:
<ul>
<li>Replace <strong>FEDLET_ENTITY_ID</strong> with our chosen entity ID. The entity ID could be anything, but it's quite common to just use the URL, in my case this will be <strong>http://fedlet.example.com:18080/fedlet</strong>.</li>
<li>Replace <strong>FEDLET_PROTOCOL</strong>, <strong>FEDLET_HOST</strong>, <strong>FEDLET_PORT</strong> and <strong>FEDLET_DEPLOY_URI</strong> tokens to match up with the fedlet's URL.
<li>Remove the <i>RoleDescriptor</i> and <i>XACMLAuthzDecisionQueryDescriptor</i> elements from the end of the XML.</li>
</ul>
At this point we can simply rename <i>sp.xml-template</i> to <i>sp.xml</i>.

Next step is to open up <i>sp-extended.xml-template</i> file and replace <strong>FEDLET_ENTITY_ID</strong> with the same entity ID we used in sp.xml. After doing so, let's rename the file to <i>sp-extended.xml</i>.

At this point in time, we have everything we need for REGISTERing on the testshib.org site, so let's head there and upload our metadata (sp.xml), but in order to prevent clashes with other entity configurations, we should rename the <i>sp.xml</i> file to something more unique first, like <strong>fedlet.example.com.xml</strong>.

After successful registration the next step is to grab the <a href="https://www.testshib.org/metadata/testshib-providers.xml">IdP metadata</a> and add it to the fedlet as <strong>idp.xml</strong>, but there are some small changes we need to make on the metadata, to make it actually work with the fedlet:
<ul>
<li>Remove the EntitiesDescriptor wrapping element, but make sure you copy the xmlns* attributes to the  EntityDescriptor element.</li>
<li>Since now the XML has two EntityDescriptor root elements, you should only keep the one made for the IdP (i.e. the one that has the "https://idp.testshib.org/idp/shibboleth" entityID), and remove the other.</li>
</ul>

Now one more thing to resolve is that we need to update the idp-extended.xml file by replacing the <i>IDP_ENTITY_ID</i> to the real entity ID of the testshib instance, which should be <strong>https://idp.testshib.org/idp/shibboleth</strong>.

Next step is to edit the FederationConfig.properties and update the following properties:
<pre>
com.sun.identity.plugin.configuration.class = com.sun.identity.plugin.configuration.impl.FedletConfigurationImpl
com.sun.identity.plugin.datastore.class.default = com.sun.identity.plugin.datastore.impl.FedletDataStoreProvider
com.sun.identity.plugin.log.class = com.sun.identity.plugin.log.impl.FedletLogger
com.sun.identity.plugin.session.class = com.sun.identity.plugin.session.impl.FedletSessionProvider
com.sun.identity.plugin.monitoring.agent.class=com.sun.identity.plugin.monitoring.impl.FedletAgentProvider
com.sun.identity.plugin.monitoring.saml1.class=com.sun.identity.plugin.monitoring.impl.FedletMonSAML1SvcProvider
com.sun.identity.plugin.monitoring.saml2.class=com.sun.identity.plugin.monitoring.impl.FedletMonSAML2SvcProvider
com.sun.identity.plugin.monitoring.idff.class=com.sun.identity.plugin.monitoring.impl.FedletMonIDFFSvcProvider
com.sun.identity.saml.xmlsig.keyprovider.class=com.sun.identity.saml.xmlsig.JKSKeyProvider
com.sun.identity.saml.xmlsig.signatureprovider.class=com.sun.identity.saml.xmlsig.AMSignatureProvider
com.sun.identity.saml.xmlsig.passwordDecoder=com.sun.identity.fedlet.FedletEncodeDecode
com.sun.identity.common.serverMode=false
com.iplanet.am.server.protocol=http
com.iplanet.am.server.host=fedlet.example.com
com.iplanet.am.server.port=18080
com.iplanet.am.services.deploymentDescriptor=/fedlet
com.iplanet.services.debug.directory=/home/fedlet/fedlet/debug
com.sun.identity.saml.xmlsig.keystore=@FEDLET_HOME@/keystore.jks
com.sun.identity.saml.xmlsig.storepass=@FEDLET_HOME@/.storepass
com.sun.identity.saml.xmlsig.keypass=@FEDLET_HOME@/.keypass
</pre>

After all of this we should now have all the standard and extended metadata files sorted, so now we should just set up the Circle Of Trust between the remote IdP and the hosted SP implementation. To do that we need to edit the <i>fedlet.cot-template</i> file and replace <strong>FEDLET_COT</strong> with <strong>fedletcot</strong> (see the cotlist attribute in the extended metadata files, both of the IdP/SP extended metadata templates use fedletcot by default), and also replace the <strong>IDP_ENTITY_ID</strong> and <strong>FEDLET_ENTITY_ID</strong> to their corresponding values. As usual rename the <i>fedlet.cot-template</i> file to <i>fedlet.cot</i>.



In order to ensure that the fedlet actually picks up these settings we need to move the configuration to the home directory:
<pre>
mkdir ~/fedlet
cp conf/* ~/fedlet/
</pre>