Plugin class

The plugin class is responsible for informing AM about the details of the customized authentication node. There is little variation between the plugin class for each authentication node, other than the version number and class names within.

Authentication nodes are installed into the product using the AM plugin framework. All AM plugins are created by implementing the org.forgerock.openam.plugins.AmPlugin interface and registering it using the Java service architecture - placing a file in META-INF/services.

For plugins that provide authentication nodes, there’s an abstract implementation of the AmPlugin interface named org.forgerock.openam.auth.node.api.AbstractNodeAmPlugin.

The following is an example of the plugin class for an authentication node:

public class MyCustomNodePlugin extends AbstractNodeAmPlugin {         1

  private static final String CURRENT_VERSION = "2.0.0";               2

  @Override
  protected Map<String, Iterable<? extends Class<? extends Node>>>
  getNodesByVersion() {                                                3
        return Map.of("1.0.0", List.of(MyCustomNode.class),
                "2.0.0", List.of(MyCustomNodeV2.class));
  }

  @Override
  public void upgrade(String fromVersion) throws PluginException {     4
      pluginTools.upgradeAuthNode(MyCustomNode.class);
      pluginTools.upgradeAuthNode(MyCustomNodeV2.class);
      super.upgrade(fromVersion);
    }

  @Override
  public String getPluginVersion() {
    return MyCustomNodePlugin.CURRENT_VERSION;
  }
}

1 The name of the plugin class. This should be the class name of the node with Plugin appended. For example, MyCustomNodePlugin.

2 The current version number of the authentication node.

3 The core classes of the authentication nodes to install and register. In this example, AM will register and install two versions of the same node.

4 The core classes of the authentication nodes for plugin-specific upgrades.

AM plugins are notified of the following events:

onInstall

The plugin has been found during AM startup, and is being installed for the first time. It should create all the services and objects it needs.

onStartup(StartupType startupType)

The plugin is installed and is being started. Any dependency plugins can be relied on as having been started.

The type of startup is provided:

FIRST_TIME_INSTALL. The AM instance has been installed for the first time.
NORMAL_STARTUP. The AM instance is starting from a previously installed state, or is joining an already installed cluster.

onShutdown

The AM instance is in the process of shutting down cleanly. Any resources the plugin is using should be released and cleaned up.

upgrade(String fromVersion)

An existing version of the plugin is installed, and a new version has been found during startup. The plugin should make any changes it needs to the services and objects used in the previous version, and create all the services and objects required by the new version.

The version of the plugin being upgraded is provided.

onAmUpgrade(String fromVersion, String toVersion)

An AM system upgrade is in progress. Any updates needed to accommodate the AM upgrade should be made.

Plugin-specific upgrades shouldn’t be made here, because upgrade is called if the plugin version also changes.

The AM version being upgraded from, and to, are provided.

The plugin is responsible for maintaining a version number for its content, which is used for triggering appropriate events for installation and upgrade.

Learn more in amPlugin in the AM Public API Javadoc.

PingAM

Plugin class