How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I register or re-register a custom authentication module in AM 5.5.x, 6.x and 7.x?

Last updated Feb 24, 2021

The purpose of this article is to provide assistance on registering a custom authentication module in AM. If you make changes to the custom module code, you will need to re-register it to apply the changes.


Overview

As of AM 5.5, modules are loaded using a service loader. As a result, the process to register custom authentication modules has been simplified and involves deploying a JAR file instead of using ssoadm. See Release Notes › Important Changes to Existing Functionality for further information. If you make changes to your custom module once it has been registered, you must re-register it to apply your changes.

See the following sections for further details:

Preparing the JAR file

You must ensure you have a valid JAR file before registering or re-registering your module.

The JAR file must contain the following files, which are needed to register the module with AM:

META-INF/services/org.forgerock.openam.plugins.AmPlugin org/forgerock/openam/examples/SampleAuthPlugin.java

Where:

  • The org.forgerock.openam.plugins.AmPlugin file holds the fully qualified class name of the AmPlugin that registers the custom implementations. The org.forgerock.openam.plugins.AmPlugin file must not be renamed or placed in a different directory. For example: $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin .......... # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM. # For more information on service loading, see the javadoc for the ServiceLoader class. org.forgerock.openam.examples.SampleAuthPlugin The above file would find the org.forgerock.openam.examples.SampleAuthPlugin file and execute the file.
  • The SampleAuthPlugin Java class implements the org.forgerock.openam.plugins.AmPlugin interface. This class registers the SampleAuth implementation and the amAuthSampleAuth.xml service schema. See Authentication and Single Sign-On Guide › About the Sample Custom Authentication Module for further information on the usage of the sample files.

You can build the JAR file using Apache Maven™ as detailed in How do I customize authentication modules using source code in AM (All versions)? and Authentication and Single Sign-On Guide › About the Sample Custom Authentication Module

Registering a custom module

You can register a custom module as follows:

  1. Copy the custom authentication module JAR file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example: $ cp custom-module-X.X.X.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
  2. Restart the web application container in which AM runs to complete the registration of the custom module.

See Authentication and Single Sign-On Guide › Installing the Module for further information.

Re-registering a custom module

If you make any changes to your custom module, you must re-register the module with AM as follows:

  1. Take a backup of your configuration prior to making any changes in case you need to revert. See Maintenance Guide › Backing Up Configurations (AM 7 and later) or How do I make a backup of configuration data in AM 5.x or 6.x?
  2. Uninstall the custom module using ssoadm, for example:$ ./ssoadm delete-svc -u [adminID] -f [passwordfile] -s [service_name​]​​​​​​ replacing [adminID], [passwordfile] and [service_name] with appropriate values, where [service_name] is the service name specified in the xml service schema file. For example, in the sample amAuthSampleAuth.xml file, the service name is iPlanetAMAuthSampleAuthService:<Service name="iPlanetAMAuthSampleAuthService" version="1.0">
  3. Delete the module sub-entry in the configuration store using ldapdelete, for example:$ ./ldapdelete --hostname host1.example.com --port 50389 --bindDN uid=admin --bindPassword password "ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]" Replacing [plugin_name] and [configuration_suffix] as follows:
    • [plugin_name] - for example, org.forgerock.openam.examples.SampleAuthPlugin. You can find this in your META-INF/services/org.forgerock.openam.plugins.AmPlugin file, for example: $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin .......... # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM. # For more information on service loading, see the javadoc for the ServiceLoader class. org.forgerock.openam.examples.SampleAuthPlugin
    • [configuration_suffix] - for example, dc=openam,dc=forgerock,dc=org
  4. Delete the old JAR file in the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and replace with the updated JAR file.
  5. Restart the web application container in which AM runs to apply the changes.

See Also

How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

API Javadoc › Interface AmPlugin

ServiceLoader API specification

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12347 (AmPlugin Custom Authentication Module cannot be uninstalled or reregistered)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.