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 ch.nevis.auth.fido.uaf.sdk.dispatcher.Dispatcher, a service for dispatching tokens to third-party token-consuming services.

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 ch.nevis.auth.fido.uaf.sdk.dispatcher.Dispatcher (a class implementing this interface). This class should contain the "business logic" that sends the token via text message.

2. Annotate your implementation with @ch.nevis.auth.fido.uaf.sdk.ConfigurationKey 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 ch.nevis.auth.fido.uaf.sdk.Configurable. If the class implements Configurable, it must also implement the method initialize(Map<String,Object>). 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 annotation.

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.