Maven Overlay Project How To

Example Overlay Project

You can find an example of the results of this guide here.

If you're using Gradle, see the instructions here.

Steps to create an overlay project

1. Create a directory for the top level: mkdir example-openid-connect-overlay
2. Create example-openid-connect-overlay/pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.example</groupId>
  <artifactId>example-openid-connect-overlay</artifactId>
  <packaging>pom</packaging>
  <version>1.1-SNAPSHOT</version>
  <name>example-openid-connect-overlay</name>

  <modules>
    
    <module>my-openid-connect</module>
  </modules>

  <dependencies>
    <dependency>
      <groupId>org.mitre</groupId>
      <artifactId>openid-connect-server-webapp</artifactId>
      <type>war</type>
      <version>${mitreid-version}</version>
    </dependency>
    <dependency>
        <groupId>org.mitre</groupId>
        <artifactId>openid-connect-parent</artifactId>
        <type>pom</type>
        <version>${mitreid-version}</version>
        <scope>import</scope>
    </dependency>
  </dependencies>

  <properties>
    <java-version>1.6</java-version>
    <org.springframework-version>3.2.3.RELEASE</org.springframework-version>
    <org.slf4j-version>1.5.10</org.slf4j-version>
    <spring.security.version>3.1.0.RELEASE</spring.security.version>
    <mitreid-version>1.1.6</mitreid-version>
  </properties>

  <build>
    <finalName>my-openid-connect-server</finalName>
  </build>

</project>

This creates a project with one sub module, my-openid-connect which will hold our modifications we want to overlay. We also set some global properties (versions of MITREid Connect, Java, Spring, etc.) and the final name of the resulting war file here.

3. Create the my-openid-connect submodule

   Create the directory example-openid-connect-overlay/my-openid-connect and cd into it

4. Create example-openid-connect-overlay/my-openid-connect/pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <artifactId>example-openid-connect-overlay</artifactId>
    <groupId>org.example</groupId>
    <version>1.1-SNAPSHOT</version>
    <relativePath>..</relativePath>
  </parent>
  <artifactId>my-openid-connect</artifactId>
  <packaging>war</packaging>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
           <source>${java-version}</source>
           <target>${java-version}</target>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>org.mitre</groupId>
              <artifactId>openid-connect-server-webapp</artifactId>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
   </build>
   <dependencies>
      <dependency>
        <groupId>org.mitre</groupId>
        <artifactId>openid-connect-server-webapp</artifactId>
        <type>war</type>
        <version>${mitreid-version}</version> 
      </dependency>
      <dependency>
      	<groupId>org.mitre</groupId>
       	<artifactId>openid-connect-common</artifactId>
       	<version>${mitreid-version}</version>
      </dependency>
    </dependencies>
</project>

At this point you should be able to do a mvn package from the example-openid-connect-overlay level and you'll get a .war file at example-openid-connect-overlay/my-openid-connect/target/my-openid-connect-server.war. Remember this name was set in the example-openid-connect-overlay/pom.xml as the finalName.

6. Any files you create in the my-openid-connect maven project will be inserted into the resultant war file. If you use the same name as a file in the upstream MITREid Connect server (OpenID-Connect-Java-Spring-Server/openid-connect-server/) project that you're overlaying, such as example-openid-connect-overlay/my-openid-connect/src/main/resources/keystore.jwks, the version from the my-openid-connect project will be used in the resulting .war file. This is good for setting up things like database connections or replacing the server's keypair. You may also create new Spring beans with new names (in my-openid-connect/src/main/java/...) that implement or override the standard openid-connect beans. If you mark these with the Spring Framework's @Primary annotation, Spring will use your class instead of the default classes automatically for autowiring. You can also add additional dependencies to the my-openid-connect/pom.xml configuration file to bring in new libraries.

Files that are good and bad to overlay

Some files in the base project aren't meant to be changed by deployments and as such shouldn't be overlaid, such as web.xml and application-context.xml. Other files are good to overlay such as data-context.xml and local-config.xml. See the full description in the server configuration documentation.