How To

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

Last updated Oct 17, 2019

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 directoryFor 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 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/OpenAM (All versions)? and Authentication and Single Sign-On Guide › Creating a 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: How do I make a backup of configuration data in AM/OpenAM (All versions)? 
  2. Uninstall the custom module using ssoadm, for example:
    $ ./ssoadm delete-svc -u amadmin -f pwd.txt -s [service_name​]​​​​​​
    
    Service was deleted.
    Replacing [service_name] with 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 "cn=Directory Manager" --bindPassword password "ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]"
    
    # DELETE operation successful for DN 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 TrademarksCopyright © 2019 ForgeRock, all rights reserved.
Loading...