Deploying the SAML Extension Server Application

You must make sure that the SAML server has been properly deployed. If you installed the SAML extension server components into tomcat_home/webapps, the SAML extension should deploy automatically. If you installed the server components to some other location, you need to modify tomcat_home/conf/server.xml to deploy the application. You can either replace the existing tomcat_home/conf/server.xml file with the server.xml file generated by the installer, or add the following lines to the existing server.xml file:

<Host ...> 
   <Context path="/samlext" docBase=<SAMLEXT_HOME>/"> 
</Host ...>

The above assumes that you've installed the SAML extension server components to the samlext_home directory.

The server.xml file also defines what port the HTTP server will listen on. The server.xml file contains a section like the following:

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" 
	  port="80" 
  minProcessors="5" 
  maxProcessors="75" 
  enableLookups="true" 
  redirectPort="443" 
  acceptCount="10" 
  debug="0" 
  connectionTimeout="20000" 
  useURIValidationHack="false" />

The port attribute defines what port the HTTP server will run on. This must match the value set as the port on the SAMLExtensionServer object in the directory. Default installations of Tomcat generally are set to listen on port 8080.

Starting the Servlet Container (Tomcat)

There are a number of ways to start the Tomcat Servlet container. The most common way is to run tomcat_home/bin/Catalina.bat with the run command. On Windows* operating systems, the Tomcat installer creates a program group on the Windows Start menu. After Tomcat has been started, you can determine if the SAML extension server is deployed by entering the following URL: http://www.ichainsite.com/cmd/ext/samlext/status. This URL displays information about the running SAML extension server components. If the system is running properly, a page like Figure 24 is displayed:

Figure 24
System Status

This page shows that the system is connected to a single LDAP server at 137.65.159.66:389. If there were other LDAP servers specified, they would be displayed here. If any specified LDAP server is currently down, it is displayed in the Bad JNDI Pools list. There is also an entry for the SAMLAuthority. This is the component that loads the SAML extension server configuration from the directory. You can validate that the configuration information in the directory matches the information on this screen.

If the SAML extension server was unable to load, you might receive a 404 Page Not Found or similar error. This happens if the SAML extension server was not properly deployed. Check the SAML Extension for Novell iChain Administration Guide and Tomcat logs for information on why the application was not deployed.

If the SAML extension server was able to load but encountered errors, this page should tell you generally what went wrong. A common problem is that the configuration LDAP server could not be accessed or the required configuration details were not found in the directory.

Testing the Loopback Affiliate Links

After the SAML extension server has been configured and deployed, you can begin testing it. Access the main iChain Site sample application by entering the following URL: http://www.ichainsite.com/ic/portal. You should be prompted to authenticate to iChain. After successful login, you should receive a page like the one shown in Figure 25:

Figure 25
iChainSite: Successful Login

The two links of interest here are Loopback Post and Loopback Artifact. The post link performs a SAML single sign-on operation using the SAML Browser/POST profile. The artifact link performs a SAML single sign-on operation using the SAML Browser/Artifact profile. Figure 26 shows the HTML source of the two links:

Figure 26
HTML Source of Loopback Links

Both links point back to the iChainSite host with the /cmd/ext URL switch. This indicates that the traffic is intended for the SAML extension server. The URLs https://www.ichainsite.com/cmd/ext/saml/gen/post and https://www.ichainsite.com/cmd/ext/saml/gen/afct are called Intersite Transfer URLs. They indicate that the user wants to perform a SAML single sign-on operation to a partner site, and they are used to securely send the user to that site. There are two critical URL parameters included on each URL:

• Aid: This is the affiliate ID that the user wants to access. In the example above, a loopback affiliation is being performed, so the Aid is www.ichainsite.com. This identifier must match the SiteID value stored in the directory for the partner site.

• Target: The target is a URL at the destination site that the user wants to access after single sign-on has been completed. The example above indicates that the user wants to access the /ic/portal resource at www.ichainsite.com.

Clicking either of the Loopback links causes the SAML extension server to both generate and validate a single sign-on assertion for your user. Figure 27 shows the page that is displayed if you click the POST link:

Figure 27
POST Loopback Link

There is one important difference between this page and the original: The Issuer value is now set to www.ichainsite.com. This indicates that instead of being from the origin site, you have accessed this page from an affiliate www.ichainsite.com. This means you have successfully performed SAML single sign-on.For extended debug information about what is happening during the SAML single sign-on processes, you can check the console of the servlet engine (Tomcat) running the SAML extension server. By default, debug logging is sent to this console as well as a file, wsslog.xml. The wsslog.xml file should be located at tomcat_home/bin/wsslog.xml.

What's Next

You have now concluded the setup portion of the stand-alone iChainSite SAML sample site. Continue to the following sections:

• Setting Up the eMartian Sample Site
• Setting Up the iChainSite and eMartian Sample Site Affiliation
• Fine-Tuning the SAML Extension

For more additional information, including installation and general administration, see the SAML Extension for Novell iChain Administration Guide