Preparing for Development
This chapter explains the prerequisites for customizing authentication nodes, and how to use 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, see "Creating Post-Authentication Hooks for Trees".
To prepare for creating or modifying authentication nodes, complete the following procedures:
Complete the following steps to set up your environment for building custom authentication nodes:
Ensure your BackStage account is part of a subscription:
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:
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"
Configure Maven to be able to access the ForgeRock repositories by adding your BackStage credentials to the Maven
settings.xmlfile. For details, see "How do I access the ForgeRock protected Maven repositories?" in the ForgeRock Knowledge Base.
If you want to use the archetype to create a project for custom authentication nodes, you also need access to the
forgerock-private-releasesrepository. Ensure your
settings.xmlfile 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/repo/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>
ForgeRock provides a Maven archetype for creating 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.
Ensure you have completed the steps in "To Prepare an Environment For Building Custom Authentication Nodes" before proceeding.
Complete either of the following steps to set up or download a Maven project for building custom authentication nodes:
To use the ForgeRock
auth-tree-node-archetypearchetype to generate a starter Maven project:
In a terminal window, go to a folder wherein you'll create the new Maven project. For example:
Run the mvn archetype:generate command, providing the following information:
A domain name that you control, used for identifying the project.
The name of the JAR created by the project, without version information. Also the name of the folder created to store the project.
The version assigned to the project.
The package name in which your custom authentication node classes are generated.
The name of the custom authentication node, also used in the generated
README.mdfile and for class file names.
AM stores installed nodes with a reference generated from the node’s class name. An installed node that is registered through a plugin is stored with the name returned as a result of calling
Class.getSimpleName(). AM does not 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 that the name does not collide with the names of existing nodes.
Alternatively, use the
namespaceproperty in the
@Node.Metadataannotation to change the name that is saved for the node. For example, adding
WriteFederationInformationNoderesults in that node being stored as
Currently AM provides only two namespaces in the
Namespaceenum, but you can extend this to add your own namespaces.
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.1.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
To download the project containing the default AM authentication nodes from the
If you do not already have a ForgeRock BackStage account, get one from https://backstage.forgerock.com. You cannot clone the
am-externalrepository without a BackStage account.
git clone https://myBackStageUsername@stash.forgerock.org/scm/openam/am-external.git
URL encode your BackStage Username if it contains special characters. For example : becomes
%3Aand @ becomes
Enter your BackStage password when prompted to do so.
Check out the
git checkout releases/7.1.0
The AM authentication nodes project is located in the
The Maven Project for an Authentication Node
When configuring your 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.
ForgeRock endeavours to make nodes from previous product versions binary compatible with subsequent product versions, so a node built against AM 6 APIs may be deployed in an AM 7.1 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 ForgeRock product dependencies as
providedin your build system configuration.
Repackage all non-internal, non-ForgeRock dependencies inside your own
.jarfile. 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.
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.xmlfile 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.1.3</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>
Core class for the custom authentication node. See The Node Class.
Plugin class for the custom authentication node. See The Plugin Class.
Properties file containing the localized strings displayed by the custom authentication node. See Internationalization.
You must include a
nodeDescriptionproperty in your node to ensure that it appears in the authentication tree designer. AM uses the
nodeDescriptionproperty value as the name of your node.
The authNodeName reflects the name of your authentication node. For example, the ForgeRock
auth-tree-node-archetype for Maven uses
myCustomAuthNode as the authNodeName.