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.

The set of paths scanned for plug-in JARs is controlled by the PLUGINS variable in env.conf. Ensure the following line is present in your instance's env.conf (also included in the template env.conf shipped with nevisFIDO):

PLUGINS="plugins/*"

In case you would like to specify the files directly:

PLUGINS="plugins/plugin1.jar:plugins/plugin2.jar"

This is included in the template env.conf shipped with nevisFIDO.

nevisAdmin4 deployment

In the nevisAdmin4 FIDO UAF Instance pattern, use the Custom Dependencies setting in the Advanced Settings tab. The easiest way is to upload a JAR file with Java code. This is the only option for classic VM deployments. In Kubernetes deployments, you can use a Kubernetes secret instead. This way, you can avoid committing the JAR to the deployment Git repository.

Proceed as follows:

• Create one Kubernetes Secret containing the JAR file(s) in the target namespace.
• In the Custom Dependencies field, click var to replace the direct value with an inventory variable, then enter the variable name in that field.
• Add that variable to your inventory and set its value to the file reference for the JAR file(s) stored in the Kubernetes secret, that is, reference the secret and the corresponding file path/key for each plug-in JAR.

As additional configuration may be required to use the plug-in, use the Generic nevisFIDO UAF Instance Settings pattern to add the required entries to the nevisfido.yml.

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