Products » Connect2id server » Documentation » Guides »

How to implement a Service Provider Interface (SPI) and package a JAR

This guide explains the development and packaging of Java plugins for the Connect2id server.

The server exposes over a dozen plugin interfaces, called Service Provider Interfaces (SPI). The SPI is a standard Java facility for dynamic runtime loading of bytecode that implements some interface contract, which code is typically packaged in a JAR file.

1. Set up your project

Create a new Java project with the appropriate packaging, Java version and dependencies.

Packaging

The project must create a JAR package.

Java version

Should be set to the required Java version for the Connect2id server. At the time of writing this guide this is Java 11.

Dependencies

Import the following dependencies:

<dependencies>
    <dependency>
        <groupId>com.nimbusds</groupId>
        <artifactId>c2id-server-sdk</artifactId>
        <version>[version]</version>
    </dependency>
    <dependency>
        <groupId>com.nimbusds</groupId>
        <artifactId>oauth2-oidc-sdk</artifactId>
        <version>[version]</version>
    </dependency>
    <dependency>
        <groupId>org.kohsuke.metainf-services</groupId>
        <artifactId>metainf-services</artifactId>
        <version>1.8</version>
        <optional>true</optional>
    </dependency>
</dependencies>

The com.nimbusds:c2id-server-sdk and com.nimbusds:oauth2-oidc-sdk versions should match those in the targeted minimal Connect2id server version.

How to find out the SDK versions?

Inspect the content of the c2id.war (a ZIP file) where a copy of the server's POM is stored under /META-INF/maven/com.nimbusds/c2id-server/pom.xml.

Several transitive dependencies will also be imported, such as those for the Nimbus JOSE+JWT library.

Important: If you need to import a dependency that might cause a conflict with the server's own consider shading it.

2. Programming

Implement the SPI for the plugin, which is defined in the Connect2id server SDK, and don't forget that the SDK has excellent JavaDocs too.

Git repohttps://bitbucket.org/connect2id/server-sdk

Annotate the implementing class with @MetaInfServices to have the appropriate SPI manifest file automatically generated and included in the JAR. If the SPI manifest is missing the plugin will not be loaded!

Example:

package com.example.my.c2id.plugin;

import org.kohsuke.MetaInfServices;
import com.nimbusds.openid.connect.provider.spi.claims.ClaimsSource;

@MetaInfServices
public class MyClaimsSource implements ClaimsSource {

    // Implementing code
}

For the above example the generated SPI manifest file will be located at

/META-INF/services/com.nimbusds.openid.connect.provider.spi.claims.ClaimsSource

and its content will be the class name of the implementation:

com.example.my.c2id.plugin.MyClaimsSource

3. Deployment

Add the generated JAR to the /WEB-INF/lib/ directory of the c2id.war, then deploy the WAR file to your server environment.

Some of the Connect2id server SPIs allow only a single plugin to be loaded, others multiple.

If the particular SPI contract requires there to be only one plugin instance make sure there are no other plugin JARs for the SPI in the /WEB-INF/lib/ directory. If the distributed c2id.war package includes one remove it.

If the single plugin instance for a given SPI is violated the Connect2id server will abort startup with an error.

4. Troubleshooting

The Connect2id server will log the loading of each plugin under a unique code given in the plugin documentation. You can use this code to search the logs to quickly find out if your implementation was correctly loaded.

Examples:

2017-08-07T13:39:44,634 INFO localhost-startStop-1 MAIN - [OP7101] Loaded claims source [1]: class com.nimbusds.openid.connect.provider.spi.claims.ldap.LDAPClaimsSource
2017-08-07T13:39:44,635 INFO localhost-startStop-1 MAIN - [OP7102] Claims supported by source [1]: sub email_verified address x_employee_number name nickname phone_number_verified phone_number preferred_username given_name family_name email

We also recommended that your plugin logs conditions and usage for debugging and security audit where necessary.

The Connect2id server uses the Log4j framework.

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>[version]</version>
</dependency>

The Log4j version can be found out from the Connect2id server POM, as explained above.