How To

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

Last updated Oct 21, 2019

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


Overview

A custom authentication node can be registered by deploying a JAR file. If you make changes to your custom node 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 node.

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

META-INF/services/org.forgerock.openam.plugins.AmPlugin
com/example/customAuthNode/myCustomAuthNodePlugin.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
    ..........
    
    # When distributing Covered Software, include this CDDL Header Notice in each file and include
    # the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
    # Header, with the fields enclosed by brackets [] replaced by your own identifying
    # information: "Portions copyright [year] [name of copyright owner]".
    #
    # Copyright 2017-2018 ForgeRock AS.
    #
    
    com.example.customAuthNode.myCustomAuthNodePlugin
    
    The above file would find the myCustomAuthNodePlugin file and execute the file.
  • The myCustomAuthNodePlugin Java class implements the org.forgerock.openam.plugins.AmPlugin interface. See Authentication Node Development Guide › The Plugin Class for further information.

You can use Apache Maven™ to generate the archetype, which creates a template of the Plugin installer to get you started as described in: Authentication Node Development Guide › To Set Up a Maven Project For Building Custom Authentication Nodes.

See How do I customize authentication tree nodes using source code in AM 5.5.x and 6? and Authentication Node Development Guide for further information on building the JAR file.

Registering a custom node

You can register a custom node as follows:

  1. Copy the custom authentication node JAR file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example:
    $ cp custom-node-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 node.  

See Authentication Node Development Guide › Building and Installing for further information.

Re-registering a custom node

 This section assumes you have already built your new JAR file and it contains the files outlined in the Preparing the JAR file section.

If you make any changes to your custom node, you must re-register the node 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 node using ssoadm, for example:
    $ ./ssoadm delete-svc -u amadmin -f pwd.txt -s [service_name]
    
    Service was deleted.
    Replacing [service_name] with the name of the Java file (minus the .java extension). For example, if your file is called myCustomAuthNodePlugin.java, then your service name is myCustomAuthNodePlugin.  
  3. Delete the node 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, com.example.customAuthNode.myCustomAuthNodePlugin. 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
      ..........
      
      # When distributing Covered Software, include this CDDL Header Notice in each file and include 
      # the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 
      # Header, with the fields enclosed by brackets [] replaced by your own identifying 
      # information: "Portions copyright [year] [name of copyright owner]". 
      # 
      # Copyright 2017-2018 ForgeRock AS. 
      # 
      
      com.example.customAuthNode.myCustomAuthNodePlugin
    • [configuration_suffix] - for example, dc=openam,dc=forgerock,dc=org
  4. Delete or rename 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

Authentication trees in AM

API Javadoc › Interface AmPlugin

Authentication Node Development Guide

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