Token Service Build Instructions

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

Overview

The Higgins Trust Framework consists of a set of components. In any given deployment scenario a different subset of Higgins components may need to be built. This page describes how to build Higgins STS components. First we describe generic component build requirements, then drill down into any component specific details. Check specific deployment scenarios for the set of components they require.

Pre-requisites

This section describes pre-requisites for building all Higgins STS components.

General

• J2SE 5.0 or higher
  • Download from either IBM or Sun
  • Note that support for J2SE 1.4 or higher is planned, but current code has 5.0 dependencies

Eclipse Specific

• Eclipse SDK 3.2 or higher
  • Download from Eclipse.
• Eclipse Web Tools Platform 1.5 or higher.
  • Download from Eclipse.
• SVN Plugin
  • Any svn plugin will work. The following are some options:
    • subclipse
    • Subversive - SVN Team Provider

Source Code

The Higgins Source Code is maintained in the Eclipse SVN Repository. Use the following URL to access the projects for the Token Service: https://dev.eclipse.org/svnroot/technology/org.eclipse.higgins/trunk/plugins. No userid and password is required for anonymous/read access.

Building Components

• There are three supported ways to build project components.

Using Eclipse Build

• One way to begin a build within Eclipse is to select "Project/Build All" from the menu.
• Each component project might dependent on other component projects. Therefore, projects will be built before projects that depend on them.
• If you use this method, you will need to manually export the associated "JAR" or "WAR" file for each project by selecting "File/Export/Java/JAR File" or "File/Export/Web/WAR File".

Using Ant within Eclipse

• Another way to build within Eclipse is to make sure the Ant view is open, by selecting "Window/Show View/Ant" from the menu.
  • Right-Click, Add Buildfiles..., browse to the buildfile (build.xml) you want to add and select it.
  • You can now double click the build file to build the default target, or expand it to see all the targets available.
    • Double-clicking on the appropriate target for the project, typically "WAR" or "JAR".
• Using this method the built libraries are placed into the project "./build/lib" directory.

Using Ant from Command Line

• Not yet documented.

Deploying the STS

• This section focuses on a CardSpace compatible deployment of the STS that uses the Axis 1.3 Binding and is deployed on Tomcat.

Component Dependancies

• All Higgins STS deployments require the following components:
  • Configuration:
    • org.eclipse.higgins.configuration.api (JAR File)
    • org.eclipse.higgins.configuration.common (JAR File)
    • org.eclipse.higgins.configuration.xml (JAR File)
    • org.eclipse.higgins.configuration.xrds (JAR File)
  • ICard:
    • org.eclipse.higgins.icard (JAR File)
    • org.eclipse.higgins.icard.common (JAR File)
    • org.eclipse.higgins.icard.provider.cardspace.common (JAR File)
    • org.eclipse.higgins.icard.registry (JAR File)
  • IdAS:
    • org.eclipse.higgins.idas.api (JAR File)
    • org.eclipse.higgins.idas.common (JAR File)
    • org.eclipse.higgins.idas.registry (JAR File)
    • org.eclipse.higgins.idas.spi (JAR File)
  • STS:
    • org.eclipse.higgins.sts.api (JAR File)
    • org.eclipse.higgins.sts.common (JAR File)
    • org.eclipse.higgins.sts.spi (JAR File)
    • org.eclipse.higgins.sts.server.mapper.appliesto (JAR File)
    • org.eclipse.higgins.sts.server.mapper.extension (JAR File)
    • org.eclipse.higgins.sts.server.mapper.polling (JAR File)
    • org.eclipse.higgins.sts.server.metadata (JAR File)
    • org.eclipse.higgins.sts.server.profile (JAR File)
    • org.eclipse.higgins.sts.server.trust (JAR File)
  • STS base64 and xmlsecurity: (these could be replaced by other base64 or xmlsecurity implementations)
    • org.eclipse.higgins.sts.base64.apache (JAR File)
    • org.eclipse.higgins.sts.xmlsecurity.apache (JAR File)
  • Other:
    • org.eclipse.higgins.iss (JAR File)
    • org.eclipse.higgins.messages (JAR File)
    • org.eclipse.higgins.registry (JAR File)
    • org.eclipse.higgins.util.idas.cp (JAR File)
    • org.eclipse.higgins.util.jscript (JAR File)
    • org.eclipse.higgins.util.socket (JAR File)
  • Dependent Libraries:
    • org.eclipse.higgins.dependencies.redistributable (JAR Files)

• Any useful Higgins STS deployment requires at least one Token Extension component:
  • SAML Token Extension: org.eclipse.higgins.sts.server.token.saml (JAR File)
• Typical Higgins STS deployments require at least one IdAS Context Provider component:
  • JNDI Context Provider: org.eclipse.higgins.idas.cp.jndi (JAR File)
• Typical deployments of Higgins STS requires a Binding component:
  • Axis 1.x Binding:
    • org.eclipse.higgins.sts.binding.axis1x.service (WAR File)
    • org.eclipse.higgins.sts.binding.axis1x.common (JAR File)

Servlet Container

• Assuming you will deploy the STS with the Axis 1.x Binding, you will need a servlet container.

TOMCAT

• Apache Tomcat is an open source servlet container. The STS is tested with version 5.5.20.

SSL Configuration

• CardSpace will only connect to an STS via SSL. By default TOMCAT is configured with SSL disabled.
  • Edit the "tomcat/conf/server.xml" file to remove the comments from around the SSL Connector configuration section.
  • You will need to specify a Java Key Store (JKS) file with an SSL certificate and its associated key.
    • The org.eclipse.higgins.sts.binding.axis1x.service/WebContent/ConfigurationFiles directory contains a localhost.jks file that contains an SSL certificate issued for the "localhost" server.

LDAP Directory

If you are using the JNDI Context Provider for IdAS you will need an LDAP server. Once your LDAP server is installed you will need to do some setup for the Higgins STS. The following ldif files can be used to setup some LDAP servers. Read the comments in the ldif files before using them.

Axis 1.x Binding

• Example configuration files are provided in the org.eclipse.higgins.sts.binding.axis1x.service/WebContent/ConfigurationFiles directory.
  • Copy them to another directory before customizing them for your machine. (As an example we assume the files are copied to <tomcat_install_root>/conf/higgins/sts).

localhost.jks

• This contains a signed certificate for machine "localhost" and can be used for test purposes. In production this should be replaced by certificates created for your server.

ManagedConfiguration.xml

• This XML file contains the majority of the settings that are used to configure the STS. It contains comments to describe the parts of the file that need to be customized for your deployment. You will need to change the path information to specify where you copied the configuration file "higgins.config.xml" (if you make no changes the file must be copied to the C: directory). There are many URIs that need to be customized. These all start with "https://localhost". This should be changed to the name of the machine where the STS is deployed. You must also have a certificate created for that machine and have the certificate stored in a keystore that is specified in this configuration file. There is a test certificate included in localhost.jks that will work for test purposes but it is not recommended to use this for a real deployment. If you specify your own keystore you will need to specify the keystore password and certificate aliases.

• At the end of the file is information about the context provider that will be used with idAS. The configuration is setup to use the JNDI context provider. This information needs to be changed if using other context providers.

• If you are using an LDAP context provider you will need to specify the LDAP configuration parameters (ldap hostname, port, and authentication credentials). These parameters will eventually go away when the Context Providers are used for updates.

ibm.config.xml

• Copy this file to config.xml (in the directory where you are customizing configuration files) if you are using IBM Java.
• This file needs to be copied into the tomcat install directory under common\classes\org\apache\xml\security\resource

sun.config.xml

• Copy this file to config.xml (in the directory where you are customizing configuration files) if you are using Sun Java.
• This file needs to be copied into the tomcat install directory under common\classes\org\apache\xml\security\resource

higgins.jpg

This contains the image that is displayed on the higgins card. You can replace this image if you want a different image displayed on the card.

Running the STS

Tomcat needs to be started with an argument that defines the location of the higgins sts configuration files. The following argument must be added to the server launch arguments:

-Dorg.eclipse.higgins.sts.conf="E:\apache-tomcat-5.5.20\conf\higgins\sts" -Dorg.eclipse.higgins.sts.conf.file="ManagedConfiguration.xml"

Replace "E:\apache-tomcat-5.5.20\conf\higgins\sts" with the directory name where the customized configuration files exist. Replace "ManagedConfiguration.xml" with the name of the configuration file you are using.