Overview
This blog provides a starting point for creating a custom authentication node in PingAM by walking through the process of copying and renaming the necessary files. However, it does not cover where to add your custom logic. You may need to refer to additional documentation or examples if you’re looking for guidance on implementing specific functionality.
The following examples were tested in PingAM 7.5
Example 1: OneTimePasswordSmtpSenderNode
Create a custom OneTimePasswordSmtpSenderNode by copying the existing file and renaming it to TimePasswordSmtpSenderNode:
Step 1. Navigate to the directory containing the existing authentication node classes:
cd am-external/openam-auth-trees/auth-nodes/src/main/java/org/forgerock/openam/auth/nodes
Step 2. Copy the OneTimePasswordSmtpSenderNode.java file and rename it to TestOneTimePasswordSmtpSenderNode.java
Make sure to replace all mentions of OneTimePasswordSmtpSenderNode to TestOneTimePasswordSmtpSenderNode inside the file:
cp OneTimePasswordSmtpSenderNode.java TestOneTimePasswordSmtpSenderNode.java
Step 3. Create a plugin file
- Create a file called
TestOneTimePasswordSmtpSenderNodePlugin.java
- Save it in the same directory as the node class:
am-external/openam-auth-trees/auth-nodes/src/main/java/org/forgerock/openam/auth/nodes
Step 4. Navigate to the following directory:
cd am-external/openam-auth-trees/auth-nodes/src/main/resources/META-INF/services
Step 5. Edit the Plugin file
- Open the file
org.forgerock.openam.plugins.AmPlugin
for editing:
vi org.forgerock.openam.plugins.AmPlugin
- Add the following line, make sure the name of the node matches
org.forgerock.openam.auth.nodes.TestOneTimePasswordSmtpSenderNodePlugin
Step 6. Add a Properties File for the Node
-
Create a new file named:
TestOneTimePasswordSmtpSenderNode.properties
. -
Save it in this directory:
am-external/openam-auth-trees/auth- nodes/src/main/resources/org/forgerock/openam/auth/nodes
Step 7. Build the Project
- Navigate to the
auth-nodes
directory:
cd am-external/openam-auth-trees/auth-nodes
- Run Maven to clean and build the project
mvn clean package
-
Verify that the build generates a JAR file in the
target
directory. Exampletarget/auth-nodes-7.5.1.jar
Step 8. Deploy the Node
Copy the generated JAR file to the PingAM deployment directory:
cp target/auth-nodes-7.5.1.jar tomcat/webapps/am/WEB-INF/lib
Step 9. Restart tomcat
-
Restart the Tomcat server for the changes to take effect.
-
Confirm the custom node is available in the PingAM authentication tree configuration UI:
Example Code: TestOneTimePasswordSmtpSenderNodePlugin.java
/*
* This code is to be used exclusively in connection with ForgeRock’s software or services.
* ForgeRock only offers ForgeRock software or services to legal entities who have entered
* into a binding license agreement with ForgeRock.
*/
package org.forgerock.openam.auth.nodes;
import org.forgerock.openam.auth.node.api.AbstractNodeAmPlugin;
import org.forgerock.openam.auth.node.api.Node;
import org.forgerock.openam.plugins.PluginException;
import org.forgerock.openam.sm.AnnotatedServiceRegistry;
import javax.inject.Inject;
import static java.util.Arrays.asList;
/**
* Core nodes installed by default with no engine dependencies.
*/
public class TestOneTimePasswordSmtpSenderNodePlugin extends AbstractNodeAmPlugin {
private final AnnotatedServiceRegistry serviceRegistry;
static String currentVersion = "7.4.4";
static final String logAppender = "[Version: " + currentVersion + "][Marketplace] ";
/**
* DI-enabled constructor.
* @param serviceRegistry A service registry instance.
*/
@Inject
public TestOneTimePasswordSmtpSenderNodePlugin(AnnotatedServiceRegistry serviceRegistry) {
this.serviceRegistry = serviceRegistry;
}
@Override
public String getPluginVersion() {
return currentVersion;
}
@Override
public void onStartup() throws PluginException {
for (Class<? extends Node> nodeClass : getNodes()) {
pluginTools.registerAuthNode(nodeClass);
}
}
@Override
public void upgrade(String fromVersion) throws PluginException {
pluginTools.upgradeAuthNode(TestOneTimePasswordSmtpSenderNode.class);
super.upgrade(fromVersion);
}
@Override
protected Iterable<? extends Class<? extends Node>> getNodes() {
return asList(
TestOneTimePasswordSmtpSenderNode.class
);
}
}
Example Code: TestOneTimePasswordSmtpSenderNode.properties
#
# The contents of this file are subject to the terms of the Common Development and
# Distribution License (the License). You may not use this file except in compliance with the
# License.
#
# You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
# specific language governing permission and limitations under the License.
#
# 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-2024 ForgeRock AS.
#
nodeDescription=Test Custom OTP Email Sender
nodeHelp=Sends an email containing a generated one-time password to the user.
fromEmailAddress=Email From Address
fromEmailAddress.help=Emails from the OTP Email Sender node will come from this address.
hostName=Mail Server Host Name
hostName.help=The name of the mail server OpenAM will use to send the messages.
hostPort=Mail Server Host Port
hostPort.help=The port of the mail server. The default port for SMTP is 25, if using SSL the default port is 465.
username=Mail Server Authentication Username
username.help=The username to use when the mail server is using SMTP authentication.
password=Mail Server Authentication Password
password.help=The password to use when the mail server uses SMTP authentication. This property is deprecated. \
Use the Mail Server Secret Label Identifier instead. The password is \
ignored if you set a Mail Server Secret Label Identifier.
passwordPurpose=Mail Server Secret Label Identifier
passwordPurpose.help=Label identifier used to create a secret label for mapping to the secret in the secret store. <br>\
AM uses this label identifier to create a specific secret label for this node. The secret label takes the form \
<code>am.authentication.nodes.otp.mail.{{identifier}}.password</code> where {{identifier}} is the value of \
Mail Server Secret Label Identifier. The identifier can only contain characters {{a-z}} {{A-Z}} {{0-9}} {{.}} \
and cannot start or end with {{.}}. If you set a Mail Server Secret Label Identifier and AM finds a matching secret \
in a secret store, the Mail Server Authentication Password is ignored.
sslOption=Mail Server Secure Connection
sslOption.help=This setting controls whether the authentication module communicates with the mail server using SSL/TLS.
smsGatewayImplementationClass=Gateway Implementation Class
smsGatewayImplementationClass.help=The OTP Email Sender node uses this class to send email messages. <br><br>\
The gateway class must implement the following interface: <br>\
<code>com.sun.identity.authentication.modules.hotp.SMSGateway</code>
emailAttribute=Email Attribute Name
emailAttribute.help=This is the attribute name used by the OTP Sender to email the user.
emailSubject=The subject of the email
emailSubject.help=This is the subject of the email that will be sent.
emailContent=The content of the email
emailContent.help=This is the content of the email that will be sent. All occurrence of {{OTP}} will be \
replaced with the One Time Password.
messageSubject=One Time Password
messageContent=Your One Time Password:
send.failure=An error occurred while sending the One Time Password. Please contact the system administrator.
send.success=Please enter your One Time Password, or request a new one
email.lookup.failure=Failed to find email with provided attribute. Please contact the system administrator.
email.not.found=Failed to find an email address for the specified user.
oneTimePassword.not.found=One time password not found
identity.failure=Failed to get identity with provided user name
gateway.failure=Failed to create Sms sender class
sslOption.NON_SSL=NON SSL/TLS
sslOption.SSL=SSL/TLS
sslOption.START_TLS=Start TLS
Example 2: HTTP Client Node
Create a custom HTTP Client Node by cloning the Marketplace git repo:
Step 1: Clone the Marketplace Repository
This repository contains the source code for the HTTP Client node.
Step 2. Build the project
- Navigate to the cloned repository directory:
cd tntp-restnode
- Run Maven to clean and build the project
mvn clean package
Step 3. Deploy the Node
- Navigate to the target directory:
cd target
- Copy the generated JAR file (e.g.,
http-client-7.5.0.jar
) to the PingAM deployment directory:
cp http-client-7.5.0.jar to tomcat/webapps/am/WEB-INF/lib
Step 4: Restart Tomcat
- Restart the Tomcat server for the changes to take effect.
- Confirm the custom node is available in the PingAM authentication tree configuration UI:
Additional References
Documentation
• Node development | PingAM 7.5.1
Resources:
• Refer to the GitHub Repository for additional details and updates.