Build Instructions

This project uses Maven as its build system. The project makes use of both Git submodules (to include dependencies on SECOAUTH) and Maven submodules (to organize components), which makes compilation a little tricky.

Git Checkout and Initialization

Check out the project using a normal Git clone command:

git clone https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server.git

Change into the newly checked out directory and initialize the Git submodules:

git submodule update --init --recursive

This will ensure you have a full checkout of both the OpenID Connect project and the SECOAUTH dependency. This command must be re-run whenever the reference to the upstream project changes.

A Note about Git Submodules

A Git submodule stores not only a reference to a particular Git repository (which is bound to a directory through the .gitmodules file) but also a reference to a specific revision of that repository. Therefore, if the reference to the submodule is updated, this shows up as a change in the parent module. If there are any local changes checked in to the submodule, and this reference is pushed up to the repository, this will break the build for anyone pulling down updates since their local copy of the submodule will not have the revision now referenced by the parent project.

Project Layout

The project has a hierarchical layout:

OpenID-Connect-Java-Spring-Server
 +-- openid-connect-common
 +-- openid-connect-client
 +-- openid-connect-server
 \-- spring-security-oauth
     +-- spring-security-oauth2

The root of the project contains a pom.xml file that references all sub-modules.

Building with Maven

The project uses the Maven "package" directive to build from the root of the project:

mvn package

By building in the root, Maven automatically builds all dependencies. Building directly in the submodules will likely fail as the cross-dependencies on other portions of the project (such as the server's dependency on common) will not have been built yet.

This recursively builds the spring-security-oauth library as well as all portions of the project. The build process produces a .jar file for openid-connect-common and openid-connect-client and a .war file for openid-connect-server.

Common Maven Options

To skip unit tests, add this option:

mvn -DskipTests package

To skip JavaDoc generation (which is triggered automatically in SECOAUTH):

mvn -Dmaven.javadoc.skip=true package

To configure an http and https proxy, add this option (especially because Maven on Linux doesn't always read the settings.xml file):

mvn -Dhttp.proxyHost=proxy -Dhttp.proxyPort=80 -Dhttps.proxyHost=proxy -Dhttps.proxyPort=80 package

Data Connection

The project is configured out of the box to connect to a MySQL server running on localhost with a default database name of "oic", and a default username of "oic" with a password of "oic". To change these, edit the dataContext.xml configuration file (or use an alternative method like MVN War Overlays). Be very careful to not check in any sensitive passwords or other information (such as the connection configuration to any integration or production servers) to the repository.

JCE

The project uses JCE through BouncyCastle. Your system may be set up to handle this already, in which case no further action is needed.

If you run into javax.crypto.JceSecurity errors, do the following:

1. Add the BouncyCastle Provider to your JRE/JDK, per instructions at http://www.bouncycastle.org/wiki/display/JA1/Provider+Installation/

2. Download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" for your JRE version from http://www.oracle.com/technetwork/java/javase/downloads/index.html (scroll to the bottom of the page).

3. Install the new policy files per the README file included in the download. The download contains new versions of local_policy.jar and US_export_policy.jar. These files must be placed in your jre/lib/security folder(s - multiple on Windows), replacing the current files. If you wish to at some point revert back to your original policy files, store the original files elsewhere.

Deploying with Tomcat

To deploy the Server, copy the generated .war file to the tomcat directory, such as:

cp openid-connect-server/target/openid-connect-server.war /var/lib/tomcat6/webapps