PingAM 7.5.1

Prepare for development

This page explains the prerequisites for building custom authentication nodes, and shows how to use either a Maven archetype, or the samples provided with AM, to set up a project for building nodes.

For information about customizing post-authentication hooks for a tree, refer to Create post-authentication hooks for trees.

Prepare an environment for building custom authentication nodes

  1. Make sure your Backstage account is part of a subscription:

    • In a browser, go to the Backstage website and sign on or register for an account.

    • Confirm or request your account is added to a subscription. Learn more in Getting access to product support in the Knowledge Base.

  2. Install Apache Maven 3.2.5 or later, and Oracle JDK or OpenJDK version 11 or later.

    To verify the installed versions, run the mvn --version command:

    $ mvn --version
Maven home: /usr/local/Cellar/maven/3.6.0/libexec
Java version: 11.0.4, vendor: AdoptOpenJDK, runtime: /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.16", arch: "x86_64", family: "mac"

  3. Configure Maven to be able to access the proprietary repositories by adding your Backstage credentials to the Maven settings.xml file. Learn more in How do I access the proprietary protected Maven repositories?.

    If you want to use the archetype to create a project for custom authentication nodes, you also need access to the forgerock-private-releases repository. Ensure your settings.xml file contains a profile similar to the following:

    <profiles>
  <profile>
  <id>forgerock</id>
  <repositories>
      <repository>
          <id>forgerock-private-releases</id>
          <url>https://maven.forgerock.org:443/artifactory/private-releases</url>
          <releases>
              <enabled>true</enabled>
              <checksumPolicy>fail</checksumPolicy>
          </releases>
          <snapshots>
              <enabled>false</enabled>
              <checksumPolicy>warn</checksumPolicy>
          </snapshots>
      </repository>
  </repositories>
  </profile>
</profiles>
<activeProfiles>
  <activeProfile>forgerock</activeProfile>
</activeProfiles>

Set up a Maven project to build custom authentication nodes

Ping Identity provides a Maven archetype that creates a starter project, suitable for building an authentication node. You can also download the projects used to build the authentication nodes included with AM and modify those to match your requirements.

Complete the steps in Prepare an environment for building custom authentication nodes before proceeding.

Complete either of the following steps to set up or download a Maven project to build custom authentication nodes:

  1. To use the auth-tree-node-archetype archetype to generate a starter Maven project:

    • In a terminal window, go to a folder where you’ll create the new Maven project. For example:

      $ cd ~/Repositories

    • Run the mvn archetype:generate command, providing the following information:

      groupId

      A domain name that you control, used for identifying the project.

      artifactId

      The name of the JAR created by the project, without version information. Also the name of the folder created to store the project.

      version

      The version assigned to the project.

      package

      The package name in which your custom authentication node classes are generated.

      authNodeName

      The name of the custom authentication node, also used in the generated README.md file and for class file names.

      AM stores installed nodes with a reference generated from the node’s class name. An installed node registered through a plugin is stored with the name returned as a result of calling Class.getSimpleName().

      AM doesn’t protect installed node names. The most recently installed node with a specific name will overwrite any previous installation of that node (including the nodes that are provided with AM by default). You must therefore choose a unique name for your custom node, and make sure the name isn’t already used for an existing node.

      For example:

      $ mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=customAuthNode \
  -Dversion=1.0.0-SNAPSHOT \
  -Dpackage=com.example.customAuthNode \
  -DauthNodeName=myCustomAuthNode \
  -DarchetypeGroupId=org.forgerock.am \
  -DarchetypeArtifactId=auth-tree-node-archetype \
  -DarchetypeVersion=7.5.0 \
  -DinteractiveMode=false
[INFO] Project created from Archetype in dir: /Users/ForgeRock/Repositories/customAuthNode
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.397 s
[INFO] Finished at: 2018-01-18T15:45:06+00:00
[INFO] Final Memory: 16M/491M
[INFO] ------------------------------------------------------------------------

      A new custom authentication node project is created; for example, in the /Users/ForgeRock/Repositories/customAuthNode folder.

      Example
      In this example, the archetype has created the basic structure required to create a custom authentication node.
      Figure 1. Node project created by using the archetype

  2. To download the project containing the default AM authentication nodes from the am-external repository:

    • Clone the am-external repository:

      $ git clone https://github.com/ForgeRock/am-external.git

    • Check out the release/7.5.0 branch:

      $ cd am-external
$ git checkout releases/7.5.0

      The AM authentication nodes project is located in the am-external/openam-auth-trees/auth-nodes/ folder.

      Example
      In this example, the project was cloned from the am-external repository.
      Figure 2. Node Project Cloned from the am-external repository

Tips for custom authentication node projects

When you configure a project for creating custom nodes, consider the following points:

  • Your node may be deployed into a different AM version to that which you compiled against.

    Nodes from previous product versions should be compatible with subsequent product versions; so a node built against AM 6 APIs may be deployed in an AM 7.5.0 instance.

  • Other custom nodes may depend on your node, which may be being built against a different version of the AM APIs.

  • Other custom nodes, or AM itself, may be using the same libraries as your node; for example, Guava or Apache Commons, and so on. This may cause version conflicts.

To help protect against some of these issues, consider the following recommendations:

  • Mark all product dependencies as provided in your build system configuration.

  • Repackage all non-internal, non-proprietory dependencies inside your own .jar file. Repackaged dependencies will not clash with a different version of the same library from another source.

    If you are using Maven, use the maven-shade-plugin to repackage dependencies.
Files contained in the Maven project
pom.xml

Apache Maven project file for the custom authentication node.

This file specifies how to build the custom authentication node, and also specifies its dependencies on AM components.

The following is an example pom.xml file from a node project:

<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>example-node-plugin</artifactId>
  <version>1.0.0</version>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.forgerock.am</groupId>
        <artifactId>openam-bom</artifactId>
        <version>7.2.0-SNAPSHOT</version>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>org.forgerock.am</groupId>
      <artifactId>auth-node-api</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.forgerock.am</groupId>
      <artifactId>openam-annotations</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>26.0-jre</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <configuration>
          <shadedArtifactAttached>false</shadedArtifactAttached>
          <createDependencyReducedPom>true</createDependencyReducedPom>
          <relocations>
            <relocation>
              <pattern>com.google</pattern>
              <shadedPattern>com.example.node.guava</shadedPattern>
            </relocation>
          </relocations>
          <filters>
            <filter>
              <artifact>com.google.guava:guava</artifact>
              <excludes>
                <exclude>META-INF/**</exclude>
              </excludes>
            </filter>
          </filters>
          <transformers>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
              <manifestEntries>
                <Import-Package>javax.annotation;resolution:=optional,sun.misc;resolution:=optional</Import-Package>
              </manifestEntries>
            </transformer>
          </transformers>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
authNodeName.java

Core class for the custom authentication node. See Node class.

authNodeNamePlugin.java

Plugin class for the custom authentication node. See Plugin class.

authNodeName.properties

Properties file containing the localized strings displayed by the custom authentication node. See Internationalization.

You must include a nodeDescription property in your node to ensure that it appears in the authentication tree designer. AM uses the nodeDescription property value as the name of your node.

The authNodeName reflects the name of your authentication node. For example, the auth-tree-node-archetype for Maven uses myCustomAuthNode as the authNodeName.