Build Instructions

This project is tested to build on Java 6 and Java 7. It uses Maven as its build system, and should run on both Maven 3.0+ and Maven 2.2. The project makes use of Maven submodules to organize components.

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

Project Layout

The project has a hierarchical layout:

OpenID-Connect-Java-Spring-Server
 +-- openid-connect-common
 +-- openid-connect-client
 +-- openid-connect-server

The root of the project contains a pom.xml file that references all sub-modules and manages dependencies for the entire project.

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 across. Building directly in the submodules will often 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.

The build process produces a .jar file for openid-connect-common and openid-connect-client and a .war file for openid-connect-server in the following directories:

openid-connect-client/target/openid-connect-client-{VERSION}.jar
openid-connect-common/target/openid-connect-common-{VERSION}.jar
openid-connect-server/target/openid-connect-server.war

Where {VERSION} is the current build version of the project such as 0.9.3-SNAPSHOT.

Common Maven Options

To skip unit tests, add this option:

mvn -DskipTests package

To skip JavaDoc generation:

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 server is configured out of the box to use an in-memory HyperSQL database (hsqldb). All data that the server stores, such as tokens, clients, and user authorizations, will be lost when the server is shut down. In order to persist data for longer than a single session, it is necessary to change the data source as configured in openid-connect-server/src/main/webapp/WEB-INF/data-context.xml.

The server is auto-configured with one client and four users, which are enumerated in the file openid-connect-server/src/main/resources/db/clients.sql and openid-connect-server/src/main/resources/db/users.sql. These files are automatically loaded by the hsqldb data source and can be augmented with other clients and users.

Java Cryptographic Extensions (JCE)

The project uses JCE through BouncyCastle which may require special installation. 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 webapps directory, such as:

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