Plug-Ins

Experimental

The plug-in system and provided APIs are considered experimental. They are prone to change in future releases with no ensured backwards-compatibility.

Some functionality of nevisFIDO can be extended via user-provided plug-ins.

Plug-ins can be made available to nevisFIDO as java.util.ServiceLoader services. The nevisFIDO core framework will discover and load plug-ins, and initialize them with similarly user-defined corresponding configuration.

This chapter describes the requirements and steps involved to create plug-ins, as well as the available plug-in extension points. The plug-in API interfaces are distributed in a separate JAR artifact.

Currently the only plug-in API available is Dispatcher_java, a service for dispatching tokens to third-party token-consuming services.

Installation

The Dispatcherplugin API is distributed as ZIP archives containing all the necessary artifacts which are needed to install them to your own Maven repository.

Local maven repository installation

Test client core module

Download the nevisFIDO-sdk-VERSION.zip archive from Nevis portal. Apart from the Maven artifacts (JAR, javadoc JAR, sources JAR and POM file):

Core archive contents

nevisFIDO-sdk-VERSION.zip
├── nevisfido-sdk-VERSION-javadoc.jar
├── nevisfido-sdk-VERSION-sources.jar
├── nevisfido-sdk-VERSION.jar
└── nevisfido-sdk-VERSION.pom

Unzip nevisFIDO-sdk-VERSION.zip archive in a separate directory and execute the command below from that specific directory (replace VERSION placeholders with the actual version number):

  mvn install:install-file \
    -Dfile=nevisfido-sdk-VERSION.jar \
    -DpomFile=nevisfido-sdk-VERSION.pom \
    -Dsources=nevisfido-sdk-VERSION-sources.jar \
    -Djavadoc=nevisfido-sdk-VERSION-javadoc.jar \
    -DgroupId=ch.nevis.auth.fido.uaf.sdk \
    -DartifactId=nevisfido-sdk \
    -Dversion=VERSION \
    -Dpackaging=jar

Add the library as a dependency to your project (replace VERSION placeholder with the actual version number):

<dependency>
  <groupId>ch.nevis.auth.fido</groupId>
  <artifactId>nevisfido-sdk</artifactId>
  <version>VERSION</version>
</dependency>

Using Plug-In Hooks

The implementation of a nevisFIDO plug-in involves creating a standard JDK java.util.ServiceLoader service, and making it available on the classpath of nevisFIDO. The plug-in API also provides hooks for letting plug-ins consume configuration from the main configuration file.

ServiceLoader Plug-Ins

Plug-ins use the JDK ServiceLoader framework. Essentially, a ServiceLoader plug-in consists of two elements:

• An implementation of a plug-in interface, such as the Dispatcher below.
• A provider configuration file located in META-INF/services that links the implementation class to the plug-in interface.

In addition to the standard procedure, plug-in implementations must be annotated with the @ch.nevis.auth.fido.uaf.sdk.ConfigurationKey annotation. This annotation is used to specify a unique identifier for the plug-in.

Example

Suppose you want to create the dispatcher plug-in, a dispatcher that sends tokens via text messages. Perform the following steps to implement this dispatcher plug-in:

1. Write an implementation of Dispatcher_java (a class implementing this interface). This class should contain the "business logic" that sends the token via text message.

2. Annotate your implementation with ConfigurationKey_java to declare your desired plug-in identifier.

3. Create a provider configuration file at META-INF/services/ch.nevis.auth.fido.uaf.sdk.dispatcher.Dispatcher with the following content:

   com.example.dispatcher.MyDispatcher

   The content of this file must be the fully qualified class name of your dispatcher implementation from the first step.

4. Pack your implementation and provider configuration file in a JAR file.

5. Make your JAR available on the Java classpath of nevisFIDO. A restart is required.

After you have completed these steps, you can configure your dispatcher in the main configuration file of nevisFIDO.

Configuration

Plug-in implementations can obtain configuration data from the main configuration file. Configuration data is opt-in.

A plug-in class can choose to implement the interface Configurable_java. If the class implements Configurable, it must also implement the method configure_java. By doing so, the plug-in class will receive a map with configuration data from nevisfido.yml at plug-in loading time.

The configuration data is specific to the plug-in. The data is selected from the main configuration file using the plug-in identifier declared with the ConfigurationKey_java annotation.

For example, if the plug-in is a dispatcher that must be identified as my-dispatcher, the identifier must be included in nevisfido.yml:

  dispatchers:
    - type: my-dispatcher
      my-attribute: my-value

The plugin implementation must be annotated as:

@ConfigurationKey("my-dispatcher")
public class MyDispatcher implements Dispatcher, Configurable {
    [...]

   public void Configure()
}

Note that the method configure (the dispatcher implements Configurable) will receive a Map with one key (my-attribute) and one value (my-value).

Deployment

To use a plug-in JAR with nevisFIDO, the JAR needs to be deployed to a nevisFIDO instance.

Each nevisFIDO instance has an associated instance directory. A nevisFIDO instance directory contains an (initially empty) plugins directory. JARs in this directory are scanned at start-up for plug-in implementations. Place your plug-in JARs in this directory to make them available to the nevisFIDO instance.

Example

The following code shows a simple dispatcher that creates an out-of-band payload that is compatible with the Nevis Mobile Authentication SDK and returns the payload in the HTTP response.

Dispatcher Example