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 May 10, 2022

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 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 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 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 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 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?

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 © 2022 ForgeRock, all rights reserved.