Release Notes - SAML Extension for Novell iChain July 1, 2003 Table of Contents 1.0 Known SAML Extension Issues 1.1 Installing the SAML Extension Server 1.2 SAML Extension Installation Requires Tomcat Documentation 1.3 Verifying the SAML Server's Basic Operations 1.4 Doctype Must Be Commented Out if No Public Access is Available by Tomcat 3.3 1.5 SAML Server Cannot Be Refreshed Over a Secure Connection 1.6 Re-Associating a SAML Attribute With an iChain Service Object Class 1.7 Rename File In Case Of Tomcat Java Exception Errors 1.8 Trusted Root Container Is Not Used For Mutual Authentication When Secure Exchange Is Disabled 1.9 SAML Assertion Consumption Prohibits Single Sign-On When Accelerator Is Configured for SSL 1.10 Forwarding a User Password to an Affiliate Site 1.11 Installing the SAML Extension Server on NetWare 6 SP3 2.0 SAML Extension Documentation 2.1 Accessing the Latest SAML Extension Documentation 3.0 SAML Extension Sample Code Documentation 3.1 Configuring a Sample SAML Extension Site 4.0 Legal Information 4.1 Disclaimer, Copyright, and Patents 4.2 Trademarks 1.0 Known SAML Extension Issues 1.1 Installing the SAML Extension Server The SAML extension server installation uses the TOMCAT_HOME or CATALINA_HOME and the JAVA_HOME environment variables in order to detect the Tomcat version that is being used and the location of the JRE. Before you install the server, you should verify that these variables are set. 1.2 SAML Extension Installation Requires Tomcat Documentation The SAML extension for Novell iChain install uses the Tomcat documentation to verify the version of Tomcat that is installed. If the Tomcat documentation is not installed, the SAML installation will fail. If you encounter this problem, you must install the Tomcat documentation, then run the SAML installation again. 1.3 Verifying the SAML Server's Basic Operations To verify the SAML server's basic operations, you can use the following URLs: http://samlext/status http://samlext/test where resolves to the address where the Tomcat/ SAML server is running. If you are using iChain and its ISO has been configured to use this SAML server, you should also be able to use the following URLs to verify basic operations: http:///cmd/ext/samlext/status http:///cmd/ext/samlext/test where resolves to an iChain address. You should be aware that the information returned from these testing URLs contains information that might be confidential, and could be retrieved by anyone who knows the iChain server's address. For beta testing, you should not use an IP address on your iChain server that could be accessed by untrusted parties. This is viewed as a debugging tool, and is disabled by default. To turn it on, add the following to the samlconfig.xml file: true The following entry will turn this option off: true 1.4 Doctype Must Be Commented Out if No Public Access is Available by Tomcat 3.3 In the web.xml file installed by the SAML extension, there is a doctype tag that is used for validation by the xml parser used by Tomcat. Within this tag, there is a link to a DTD located on the Sun site (java.sun.com). If your Tomcat server does not have access to this site, it will not be able to download the DTD, nor will it be able to validate the xml file. If the xml parser cannot validate the xml file, SAML will not load. You can resolve this issue on Tomcat 3.3 by commenting out this tag using standard xml comments (). 1.5 SAML Server Cannot Be Refreshed Over a Secure Connection The ConsoleOne snap-ins cannot refresh the SAML extension server over a secure connection. To refresh the server, you must manually refresh it or use a non-secure connection. 1.6 Re-Associating a SAML Attribute With an iChain Service Object Class The SAML schema will add an attribute to the iChain Service Object class. If the iChain schema is re-extended after extending the SAML schema, the new attribute will be removed from the iChain Service Object class. This will require the attribute to be re-associated with the iChain Service Object Class, either manually or by creating a new SAML extension server. You then need to go to the iChain Service Object general page and re-select your SAML extension server object. 1.7 Rename File In Case Of Tomcat Java Exception Errors Some versions of Tomcat install a xercesImpl.jar file that conflicts with the xercesImpl.jar that is put in TOMCAT_HOME\webapps\samlext\WEB-INF\lib\ during the SAML extension installation. In those cases, we rename the xercesImpl.jar in TOMCAT_HOME\webapps\samlext\WEB-INF\lib\ to xercesImpl.saml. Other versions of Tomcat do not install xercesImpl.jar. In these cases, xercesImpl.jar is left as-is in the TOMCAT_HOME\webapps\samlext\WEB-INF\lib\ directory. Novell has tested these cases for accuracy, however, if the SAML extension server fails to initialize and reports java exception errors, you should go to the TOMCAT_HOME\webapps\samlext\WEB-INF\lib\ directory and verify that: - xercesImpl.jar has been renamed as xercesImpl.saml when xercesImpl.jar already exists in the java classpath or - xercesImpl.jar has not been renamed as xercesImpl.saml when xercesImpl.jar does not already exist in the java classpath. 1.8 Trusted Root Container Is Not Used For Mutual Authentication When Secure Exchange Is Disabled SSL mutual authentication will not work with an accelerator that does not have secure exchange enabled simply by putting the issuer (Certificate Authority) of the client's SAML server certificate into the trusted root container configured in the ISO object. However, if Secure Exchange is enabled on the accelerator, putting the issuer (Certificate Authority) of the client's SAML server certificate into the trusted root container configured in the ISO object will always allow SSL mutual authentication to work. To resolve the problem in the case where Secure Exchange is not enabled, try one of the following: 1) The iChain server certificate used for the accelerator (the one configured in iChain Admin utility under Configure > Web Server Accelerator > Modify > Certificate) needs to be signed by the same Certificate Authority as the SAML server's client certificate (the one configured in samlextConfig.xml with the usage="ssl"). or 2) The iChain server certificate used for the accelerator (the one configured in iChain Admin utility under Configure > Web Server Accelerator > Modify > Certificate) needs to be created after the issuer (Certificate Authority) of the client's SAML server certificate is put into the trusted root container configured in the ISO object. or 3) The iChain server certificate used for the accelerator (the one configured in iChain Admin utility under Configure > Web Server Accelerator > Modify > Certificate) needs to be backed up, deleted, and restored after the issuer (Certificate Authority) of the client's SAML server certificate is put into the trusted root container configured in the ISO object. A SAML SOAP responder URL of "https:///cmd/mutExt/ samlext/saml/resp" uses mutual authentication and might run into the same issue. The same workaround might be necessary. 1.9 SAML Assertion Consumption Prohibits Single Sign-On When Accelerator Is Configured for SSL SAML assertion consumption does not allow single sign-on when the accelerator is configured for SSL. This is the nature of SSL mutual authentication. The configuration of the Artifact receiver URL, the POST receiver URL, and the SOAP responder URL should not point to an accelerator that is configured for SSL mutual authentication. 1.10 Forwarding a User Password to an Affiliate Site After authenticating to iChain through SAML, back-end Web applications accessed through accelerators using an LDAP profile with the option "Allow authentication through HTTP authentication header" enabled will prompt the user for login, since SAML does not populate the HTTP Authorization header. However, the accelerator option "Forward authentication information to web server," OLAC, and FormFill can be used to provide single sign-on to back-end Web applications after SAML has provided user authentication to the site. See the SAML Extension for Novell iChain Admininistration Guide for information on how to forward the user's iChain password to an affiliate site for use with Forward Authentication and OLAC. 1.11 Installing the SAML Extension Server on NetWare 6 SP3 Before installing the SAML extension server on NetWare, you need to install JVM 1.4.1 for NetWare. You can download JVM 1.4.1 for NetWare by going to http://download.novell.com. Click Consolidated Support Packs > JVM v1.4.1 for NetWare, then download the installation executable. To install the SAML extension server on Netware: 1) Extract the zip file in the sys volume. This will create a folder in the sys volume called SAML. 2) From the server console, run sys:/saml/install.ncf. If you extract the zip file anywhere else, you need to modify the install.ncf file to reflect the new path to the setup.jar file. 2.0 SAML Extension Documentation 2.1 Accessing the Latest SAML Extension Documentation For the latest SAML extension for Novell iChain documentation, including information on SAML extension installation and administration, go to http://www.novell.com/documentation/lg/ saml/index.html. 3.0 SAML Extension Sample Code Documentation 3.1 Configuring a Sample SAML Extension Site For information on how to configure the sample code available with the SAML download, see the Sample Site Setup Guide at http://www.novell.com/ documentation/lg/saml/index.html. 4.0 Legal Information 4.1 Disclaimer and Copyright Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. You may not export or re-export this product in violation of any applicable laws or regulations including, without limitation, U.S. export regulations or the laws of the country in which you reside. This product may require export authorization from the U.S. Department of Commerce prior to exporting from the U.S. or Canada. Copyright (C) 2003 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. 4.2 Trademarks iChain, NetWare, and Novell are registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.