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.
Check out the project using a normal Git clone command:
git clone https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server.git
The project has a hierarchical layout:
OpenID-Connect-Java-Spring-Server
+-- openid-connect-common
+-- openid-connect-client
+-- openid-connect-server
openid-connect-common, openid-connect-client, and openid-connect-server are each managed as individual Maven submodules. The root of the project contains a pom.xml file that references all sub-modules and manages dependencies for the entire project.
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 submodules. 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.
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
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 edited to hold other clients and users.
The project uses JCE through BouncyCastle which may require special installation. If you run into javax.crypto.JceSecurity errors, do the following:
-
Add the BouncyCastle Provider to your JRE/JDK, per instructions at http://www.bouncycastle.org/wiki/display/JA1/Provider+Installation/
-
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).
-
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.
The openid-connect-server-webapp module will produce a packaged WAR file that can be deployed to a number of different servlet containers. To configure the server for local use, see the Server Configuration documentation. Most importantly, the issuer value in the server configuration bean needs to be set to the URL that the server can be accessed from. The default value for the issuer is http://localhost:8080/openid-connect-server-webapp/.
The server webapp can be deployed using an embedded Jetty instance inside of Maven. To deploy to Jetty, first install the application to your local Maven repository by running this from the parent project directory:
mvn clean install
To run the embedded Jetty server and deploy the server webapp, run the following command from the openid-connect-server-webapp directory (important: do not run this command from the parent project directory).
mvn jetty:run
This will deploy the server to http://localhost:8080/openid-connect-server-webapp/.
The server webapp has been tested with Tomcat 6 and Tomcat 7. To deploy the server to Tomcat (or a similar servlet container), copy the generated .war file to the appropriate Tomcat webapps directory, such as:
cp openid-connect-server-webapp/target/openid-connect-server.war /var/lib/tomcat6/webapps
