DevelopmentEnvironmentSetup

Owned by Scott Cantor
May 02, 2023
3 min read

Extensive discussion of how we develop the components under Eclipse can be found in the Java Developer's Guide. While it is not strictly necessary to align one's Eclipse environment to that degree, there are advisable practices to be found there.

Generally speaking, development of most extensions can be done via Maven without actually downloading and importing projects from the Shibboleth code base. In some cases, particularly where development of web flows is concerned, it is typically easiest to import at least some of the projects in order to run a "testbed" project developed alongside the IdP to exercise flows in a real world environment.

Development other than via maven is not supported.

Maven Artifacts

The Maven coordinates for Shibboleth code artifacts can be found by browsing our Nexus release repository.

As multi-module projects, both OpenSAML and the IdP contain a large number of individual artifacts, and your dependencies will be directly to the specific API modules you need, not to the "whole" project. Per the Java Product Version Policy, you should not be establishing non-test dependencies on modules containing only implementation classes unless you're prepared to give up compatibility assumptions across versions. Implementation classes can change incompatibly, even in a simple patch.

Building Shibboleth Projects Locally

Should you wish to include the OpenSAML and/or IdP projects in your workspace, you can follow the outline below. You will likely only need the the IdP code depending on what you're doing. Before you get started be sure to have Maven V3 installed.

Generally you will want to pull a tagged release of the products based on the version you want to develop/baseline with. Most active development takes place on the trunk, though branches may exist at times if we're actively working across two minor versions.

To get the OpenSAML code, if necessary:

  1. Check out the OpenSAML project (see Source Code Access).

  2. Change to the opensaml-parent directory.

  3. Build and install the project using 'mvn -DskipTests -Dmaven.javadoc.disable=1 clean install'. If you want to include the unit testing or javadoc phases, adjust accordingly.

To get the Identity Provider code:

  1. Check out the Identity Provider project (see Source Code Access).

  2. Change to the idp-parent directory.

  3. Build and install the project using 'mvn -DskipTests -Dmaven.javadoc.disable=1 clean install'. If you want to include the unit testing or javadoc phases, adjust accordingly.

Now you can begin working with the project in whatever development environment you choose.

The additional project you may want to pull down is the java-idp-testbed project (see below).

Using Eclipse

Currently, all of the Shibboleth Java developers use Eclipse for development. In addition to the material under Java Developer's Guide, the following may be useful:

To get the OpenSAML code:

  1. Check out the OpenSAML project (see Source Code Access). Note, this "top-level" project isn't a Java project so it won't show up in the Package Explorer.

  2. In the Package Explorer right click and select Import -> Maven -> Existing Maven Project and select opensaml-parent as the root directory.

To get the Identity Provider code:

  1. Check out the Identity Provider project (see Source Code Access). Note, this "top-level" project isn't a Java project so it won't show up in the Package Explorer.

  2. In the Package Explorer right click and select Import -> Maven -> Existing Maven Project and select idp-parent as the root directory.

The java-idp-testbed project can also be checked out and imported, and it contains an Eclipse launch script to run the testbed as a Java application.

Using the Testbed

If you can live with a test environment that uses the latest snapshots, the java-idp-testbed project launches an embedded Jetty container to run the IdP locally. Modifying the POM to reference any extension projects of your own may (emphasis on may) allow you to run those extensions by configuring the IdP to use them.

The testbed project operates by loading the IdP configuration files from the local classpath, which is drawn from the checked out projects. You can change the IdP configuration "in-situ" within the idp-conf, idp-war, idp-distribution, etc. projects and alter the behavior of the testbed.

A README file in the project outlines how to run the testbed with Eclipse, simply by running Main.java as a Java Application.