Deploying and Configuring the Bandit IdP

Introduction

This page contains general instructions for deploying and configuring the Bandit IdP. We have assumed that prior to deploying the IdP, you have installed a system that can properly host the IdP. However, we recognize that this process can be difficult and error prone. There are many things that must be properly setup. We have attempted to document these kinds of issues (see here). It would be well worth your time to read through these notes before installing the IdP to ensure that your system is properly set up.

We have also included a section that contains links to notes created by others who have deployed the IdP (see here). Their notes may contain very helpful hints and suggestions for you examine before you deploy the IdP.

Finally, we strongly recommend that you read through the entire set of instructions on this page before you begin deployment. It may bring things to your attention that will save you time and effort as you go about deploying the IdP.

Deploying As a Tomcat Servlet On Linux

It is assumed that you have already installed Tomcat on your Linux server (Note: we are assuming Tomcat5). You can deploy a .war file by simply going to the Tomcat management page in your browser, which you can get to by entering the following URL:

http://yourservername:8080

For example:

http://wag.bandit-project.org:8080

This will bring up a Tomcat Administration welcome page. On the left you will see a link called Tomcat Manager. Click that link. You may be prompted to login with your Tomcat manager name and password. Tomcat users are defined in a file on the server called $CATALINA_HOME/conf/tomcat-users.xml where $CATALINA_HOME is the root of the Tomcat installation directory. In this file you should look for a user who has the role of 'manager'.

Once you are at the management page, there will be a couple of options you can use to deploy a .war file. The .war file you want to deploy is the BanditIdP-<version>.war file that you either downloaded from our download page, or the BanditIdP.war file that you built using the instructions found on our build/test page. We recommend deploying it with the the web application name of BanditIdP:

1. The simplest method is to upload the .war file from your workstation by using the "Select WAR file to upload" input box in the "WAR file to deploy" section. You will want to rename the .war file to whatever you'd like your web application to be named. If you follow the Apache Connector instructions below, of course, you'll want to name the WAR file name to match the JkMount directive.
2. The "Deploy directory or WAR file located on server" method is usable but you cannot use the "WAR or Directory URL" input box because it will not automatically unpack the .war file which is required by the Bandit IdP install. You can however, use the "XML Configuration file URL" input box to specify deployment instructions that will allow the Bandit IdP install to complete successfully. Your Tomcat Context XML Configuration file should contain the "unpackWAR" option set to true. If you were deploying version 1.0.1322 of the Bandit IdP and wanted your application to be called "MyBanditIdP", your Context XML Configuration file would look something like this:

   <?xml version='1.0' encoding='utf-8'?>
   <Context docBase="/srv/ftp/BanditIdP-1.0.1332.war" path="/MyBanditIdP" unpackWAR="true" />
   

   This Context Configuration XML file will need to be located on the server just as the Bandit IdP .war will. In the "XML Configuration file URL" input box, you must specify the location of your Context Configuration XML file using a "file:/" scheme. If your file was called "BanditIdP.xml" and located in /srv/ftp, you'd specify "file:/srv/ftp/BanditIdP.xml" in the input box and push the Deploy button.

As an alternative to using the Tomcat management page, we have provided a simple bash script you can use to deploy the BanditIdP.war file that is found in the build subdirectory (assuming you built the war file yourself). The bash script is installidp.sh. When it is invoked, it will prompt you to enter the following parameters:

1. Name of server to deploy the war file to.
2. Web application name to assign the IdP on the server. The script deploys BanditIdP.war, which would normally have an web application name of BanditIdP on the server. However, you may specify a name other than BanditIdP.
3. Name of the tomcat manager user.
4. Password of the tomcat manager user.

All of these parameter may also be entered on the command line. Use the -help option to see how to specify these parameters on the command line.

Apache Connector

When using Tomcat with Apache, you will need to use the mod_jk plug-in. This plug-in handles communication between Tomcat and Apache.

You must add the following directive to the /etc/apache2/conf.d/jk.conf file:

   JkMount /BanditIdP/* default

The JkMount directive specifies which URI contexts are sent to Tomcat. The mod_jk module supplies the code to enable the different Tomcat workers. In the above example, we specified a context path for BanditIdP. If you named your IdP something other than BanditIdP when you deployed it (see above), you will want to specify that name instead.

For more detailed information about the Tomcat Apache connector and how to set it up, see the Tomcat Apache Connector Website

Java Version Notes

If you are using Java 1.6, you may run into problems - it appears that between Java 1.5 and 1.6, changes have been made to this method:

  javax.xml.stream.XMLOutputFactory newInstance( String, ClassLoader);

You can bypass the Java 1.6 implementation of this method by copying the stax-api-1.0.1.jar file from the BanditIdP directory to a (possibly new) directory within your Tomcat installation directory called <CATALINA_HOME>/common/endorsed.

Enabling Strong Encryption

On some platforms, the Java JVM may be not be set up to allow strong encryption. The STS that is part of the IdP requires strong encryption (AES 256 minimum). You will want to make sure you have policy jar files that allow strong encryption. Specifically, look for the following files in the jvm's jre/lib/security directory:

US_export_policy.jar local_policy.jar

The versions of these jar files which allow strong encryption may be found here for Java 5 and here for Java 6.

If you see the following error, you definitely do not have strong enough encryption and will have to click the link above to update your jar files:

  Exception org.apache.xml.security.encryption.XMLEncryptionException decrypting token DOM: 
    Illegal key size Original Exception: 
      java.security.InvalidKeyException: Illegal key size 

Miscellaneous Issues

This is a list of miscellaneous issues that have been discovered as people have deployed the IdP on various versions of Linux.

• Starting Tomcat With -security Option. On some systems, the default Tomcat installation is setup to start Tomcat with a -security option. this means that the security policy found in $CATALINA_BASE/conf/catalina.policy will be enforced. Unfortunately, this causes problems for Tomcat when it loads the TokenService servlet class (org.eclipse.higgins.sts.binding.axis1x.Servlet). It gets an error complaining that there is no RuntimePermission for !createClassLoader. In theory, one should be able to edit catalina.policy to grant the needed permission. However, we have not yet had time to figure out how to do this. Our current recommendation is to simply start Tomcat without the -security option. If anyone figures out how to modify catalina.policy correctly, please let us know, or feel free to modify this wiki page to explain what to do.
• Jar Files in $CATALINA_BASE/common/endorsed. The .jar files in this directory take precedence over jar files deployed from the war file. Sometimes the jar files in $CATALINA_BASE/common/endorsed are not compatible with the versions we supply in the war file. Sometimes they are older versions. This can cause a problem at run time. If you discover a conflict, you might consider moving the files in $CATALINA_BASE/common/endorsed to $CATALINA_BASE/common/lib. They are then still available to other applications that may be using them, but not as a first resort.
• Clock Issues. Make sure that the clock on your system is set correctly. Tokens issued by the IdP are stamped with the current time and have a validity period. If the time on the system hosting the IdP is incorrect, the tokens it issues may not be useable on relying parties.
• java.lang.reflect.InvocationTargetException. This error may occur because the Axiom library (axiom-api-1.2.jar) calls XMLOutputFactory::newInstance(String, ClassLoader), which is in the stax library. This call caused a NoSuchMethodError exception, which eventually causes an InvocationTargetException. In Java 6, the stax library is part of the Java environment. Java 6 has a wrong signature for the XMLOutputFactory::newInstance(String, ClassLoader) method. It returns an XMLInputFactory instead of an XMLOuputFactory. This is supposed to be fixed in later versions of Java (presuming later versions come out). The Axiom 1.2.8 library works around this bug by using the XMLOutputFactory::newInstance() method instead of XMLOutputFactory::newInstance(String, ClassLoader). You may be able to fix this problem by replacing the axiom-api, axiom-dom and axiom-impl libraries in Bandit IdP with version 1.2.8.

Configuring The IdP

Once the IdP is installed, all IdP configuration is done via a browser over the web. When you enter the URL for the IdP, it will determine if it has been installed and configured. If not, it will automatically lead you through the steps of configuration. The URL for the application is as follows:

http://yourserver/BanditIdP/index.jsp

For example:

http://wag.bandit-project.org/BanditIdP/index.jsp Note that in this example, the IdP application name is BanditIdP. If you gave the IdP another name when you deployed it, you should use that name.)

Note that this URL is the one that regular users would use. If the application has not been installed and configured, it will redirect to an administrative page that will perform the installation. The administrative page is invoked as follows:

http://yourserver/BanditIdP/admin.jsp

For example:

http://wag.bandit-project.org/BanditIdP/admin.jsp (Note once again that you should use the name you gave the IdP instead of BanditIdP)

You may go directly to this URL any time to perform administrative actions. The first time you go to this page, you will be led through an installation process. After that, you will be required to login with an administrator's password if you want to change installation settings.

The installation process consists of the following steps:

1. Define configuration directory, configuration file names, and administrative password.
2. Define user attributes.
3. Define card templates.
4. Define Java keystore.
5. Define IdAS context provider.
6. Verify/finish installation.
7. Restart IdP.

These are described in the following sections.

Define Configuration Files and Admin Password

At this step of the installation, the user will be prompted to enter a directory where configuration files will be stored. The user also specifies the name of the IdP configuration file and the STS configuration file. If the files already exist from a prior installation, the installation process will behave as an upgrade. When doing an upgrade, the installation process will read existing configuration information to pre-populate forms with data that was previously configured. When doing an upgrade, the user will normally have to enter very little, if any, configuration information.

In addition to specifying configuration directory and file names, the user will be required to enter an administrative password that will be required to modify configuration settings after the installation is completed.

Note for first-time installers: The configuration directory does not have to be within the application server directory, and it must exist and have correct permissions before it is specified.

Define User Attributes

At this step of the installation, the user specifies the list of attributes can be set on user objects in the identity store.

Define Card Templates

At this step of the installation, the user specifies card templates. Card templates determine what kinds of information cards the IdP can issue to end users. Each template specifies the list of claims (attributes) that the card will provide when it is selected for use at a relying party.

Define Java Keystore

At this step of the installation, the user specifies a Java keystore which holds the certificates and private keys that are used to sign and encrypt information cards and security tokens issued by the STS. The user may specify an already existing keystore, or they may create a new one. In order to create a new keystore, they will need to have private key and certificate files in PEM format.

Define IdAS Contexts

At this step of the intallation, the user may create one or more IdAS contexts, and then select one to be the current context for the installation.

When adding a new context, or editing an existing context, the user specifies the following items:

1. Context ID. This is a URI that uniquely identifies the context.
2. Context Display Name. This is the name of the context that will be displayed in a drop-down list of currently defined contexts. The user is allowed to select one of these as the current context for the IdP.
3. Context Provider Handler. This is a Java class that knows how to configure a specific context provider, as well as do context provider specific actions. The other settings displayed on the configuration screen are determined by this class. The screen is customized based on the context provider handler that is specified. Currently, there are two context provider handler classes that are shipped with the IdP. These are as follows:

org.bandit.idp.cphandlers.JndiContextProviderHandler. Enter this class if you want the context to be a JNDI context. Currently, the only supported JNDI backend store is an LDAP server. Thus, the JndiContextProviderHandler class really only knows how to configure the context provider to connect to an LDAP server.

org.bandit.idp.cphandlers.FileContextProviderHandler. Enter this class if you want the context to be an XML file context. The backend for an XML file context is a simple XML file. The context provider handler class will present a screen to enter an XML file name that is to be the data repository. Besides editing the XML file via the IdP (using IdAS), a user is also allowed to edit the XML file directly using a text editor or other tool. Changes made out-of-band by a text editor will be automatically detected and incorporated by the XML file context provider.

XML File Context File Format

This section describes the format of the XML file for an XML file context. The following example illustrates (inline comments describe the various XML elements and attributes):

<?xml version="1.0" encoding="UTF-8"?>

<!-- The <Context> element defines the context -->

<Context>

<!--
Nodes are defined by the <Node> element. The NodeType attribute specifies the type of the node
-->

<Node NodeType="http://www.eclipse.org/higgins/ontologies/2006/higgins#Person">

<!--
Attributes are defined by the <Attribute> element. The AttrID attribute specifies the type of the attribute. The DataType attribute specifies the data type for the attribute values. Note that the context provider determines if an attribute is simple or not by the DataType attribute. These are basically the well known types defined in the idas.spi.ITypedValue interface. Any data types other than these will be considered to be complex types.

IMPORTANT NOTE: There are three attribute IDs that have predefined meanings. These are as follows:

http://www.eclipse.org/higgins/ontologies/2006/higgins#userName. This is the attribute whose value will be the node ID that gets returned. It is also used in conjunction with the password attribute when a context is opened using the username/password credential type.

http://www.eclipse.org/higgins/ontologies/2006/higgins#password. This is the attribute where the user password is stored (if any). This is used in conjunction with the user name attribute when a context is opened using the username/password credential type.

http://www.eclipse.org/higgins/ontologies/2006/higgins#cardKeyHash. This is the attribute where information card key hashes are stored. Card key hash values are used to open contexts using the self-issued credential type.

-->

<Attribute AttrID="http://www.eclipse.org/higgins/ontologies/2006/higgins#userName"

   DataType="http://www.w3.org/2001/XMLSchema#string">

<!--
Attribute values are defined by the <AttributeValue> element. Simple attribute values are stored directly in the element. Complex attribute values will have a sequence of nested <Attribute> elements
-->

<AttributeValue>admin</AttributeValue>

</Attribute>

<Attribute AttrID="http://www.eclipse.org/higgins/ontologies/2006/higgins#password"

   DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>adminpassword</AttributeValue>

</Attribute>

</Node>

</Context>

Verify/Finish Installation

The last step of the installation displays a list of files that will be created, copied, or updated. Because the installation may actually be an upgrade, any existing configuration files will be backed up before they are overwritten. The user will be given the opportunity, if desired, to specify that certain files NOT be copied and/or backed up.

Restart IdP

The last thing the installation process does is to update certain parameters in the web.xml file for the web application. It is the presence of these parameters in the web.xml file that tells the IdP whether or not the installation is complete. However, the act of updating the web.xml file does NOT cause the application to see these updated parameters, because they are cached by Tomcat. Hence, it is necessary to restart the IdP. A page with a restart link is presented. It contains the following URL:

http://yourserver:8080/manager/reload?path=%2FBanditIdP

For example:

http://wag.bandit-project.org:8080/manager/reload?path=%2FBanditIdP (Note again that your IdP may be called something other than BanditIdP)

When you click the link, you may be prompted to enter the Tomcat manager user name and password.

Until the IdP is successfully restarted, it will not be aware that the installation was successfully completed, and any attempt to access the IdP's main page (index.jsp) will be redirected to the administrative page where it will attempt to do installation.

If the link does not successfully restart the application, you may want to go to the Tomcat Manager page and manually stop and then restart the application. If that doesn't work, login to your server and restart Tomcat itself.

Notes From Users Who Have Installed the Bandit IdP

This section contains links to notes contributed by users who have installed the Bandit IdP. These links may provide helpful hints and solutions for problems and issues you may encounter as you install the Bandit IdP.

1. Bandit IdP Installation Notes. Author: Gene Gotimer from Privo www.privo.com.
2. Setting up a Certificate Authority (CA) for use with Tomcat and BanditIdP. Author: Gene Gotimer from Privo www.privo.com.