Building an Extension

Tools

• Language: Java 8 

• Packaging: Java .jar

• Build Maven; this guide assumes the usage of Maven; you can use Gradle or others

Build the Project

To get started:

• Get the HYPR CC extension API, published as a standalone .jar

• Get the source for one of the published extensions; it's recommended to use this as a starting point

• Import the existing source into the IDE of your choice

• Change directory to the <checkout dir> and run mvn clean package

Add Logic

Customize the extension code to add your custom logic.

An extension is an implementation of the CC plugin API. You must extend the HyprExtension class.

Here is the outline of a typical extension:

public class MyExtension extends HyprExtension {

    public MyPlugin(PluginWrapper wrapper) {
        super(wrapper);
    }

    @Extension(ordinal = 1)
    public static class MyRegExtPoint extends AbstractRegistrationExtensionPoint {
        // Implement custom lifecycyle logic here
    }

    @Extension(ordinal = 2)
    public static class MyAuthExtPoint extends AbstractAuthenticationExtensionPoint {
        // Implement custom lifecycyle logic here
    }
}

Replace the existing ExtensionPoint code with your custom logic.

Customizing Library Dependencies

Dependencies are managed via the standard Maven/Gradle approach.

HYPR recommends minimizing the use of external libraries to keep the plugin package small and reduce the likelihood of dependency conflicts.

If you use external libraries, they must be packaged with the plugin .jar file.

The following dependencies are provided by the CC, so you do not need to package them. 

Library	Description	Version
pf4j	CC plugins are based on this library. https://pf4j.org/	2.6.0
HYPR cc-extension-api	Artifact containing CC ext. API	3.6.0
Apache httpclient	https://hc.apache.org/httpcomponents-client-4.5.x/ Useful for making external REST calls over HTTP	4.5.8

Customize Manifest.mf

CC extensions use the Java .jar manifest.mf file to provide metadata to CC.

When the extension .jar is uploaded, CC will inspect the manifest and extract the relevant information.

The manifest is automatically created by the Maven build file, using the maven-compiler-plugin.

Similar results can be achieved with Gradle.

The following is a sample manifest.mf:

Modify the following attributes in the pom.xml to match your needs. These will feed into the generated manifest file.

<properties>
        ...

        <!-- Plugin metadata, used to uniquely identify the extension -->
        <!-- The assembly plugin (below) is going to put this in the Jar Manifest.mf -->
        <extension.id>${project.artifactId}</extension.id>
        <extension.class>com.hypr.server.rp.extensions.okta.OktaExtension</extension.class>
        <extension.version>${project.version}</extension.version>
        <extension.provider>HYPR Corp</extension.provider>
        <extension.dependencies/>
    </properties>

Testing

It is recommended to unit/component test your plugin code. There are no complicated dependencies, so it is easy to add tests. Simulate the plugin configuration manually, like this:

public class MyExtensionTest {
  
  private MyPlugin.MyRegistrationExtension setupTestExtension() {
  
    MyPlugin.MyRegistrationExtension ext = new MyPlugin.MyRegistrationExtension();

    // Setup test configuration 
    PluginConfigAttribute config = new PluginConfigAttribute();
    config.setName("Attribute A");
    config.setValue("Value");

    List<PluginConfigAttribute> config = new ArrayList<>();
    config.add(config);

    // Invoke the callback to set configuration on the ext 
    // Once ext is deployed, the server does this step
    ext.setConfigAttributes(config);
    return ext;
  }
  
  @Test
  public void testReg() {
    MyPlugin.MyRegistrationExtension ext = setupTestExtension();
    // Invoke the callbacks on the ext and assert outcome
  }
}

Now that we have a plugin instance (above), you can invoke the callbacks to test relevant code.