--- title: Create tree hooks description: Create authentication tree hooks to perform custom processing after an authentication tree completes and a session is created component: pingam version: 8 page_id: pingam:am-authentication:post-authn-plugins-treehook canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/post-authn-plugins-treehook.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-06-01T14:34:20Z keywords: ["Authentication", "Nodes & Trees", "Setup & Configuration"] page_aliases: ["authentication-guide:post-authn-plugins-treehook.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authentication/post-authn-plugins-treehook.html section_ids: develop-tree-hooks-core: The core class of an authentication tree hook --- # Create tree hooks This section explains how to create a hook used by a node within an authentication tree. These tree hooks can perform custom processing after an authentication tree has successfully completed and a session has been created. AM includes the following authentication tree hooks: | Tree hook | Used by node | Details | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CreatePersistentCookieTreeHook` | [Set Persistent Cookie node](https://docs.pingidentity.com/auth-node-ref/8/set-persistent-cookie.html) | Creates a JWT with the session, encryption, and node details. The JWT is then used to set a persistent cookie on the response. | | `ErrorDetailsTreeHook` | [Set Error Details node](https://docs.pingidentity.com/auth-node-ref/8/set-error-details.html) | Adds error details to the response.You can inject a [TreeFailureResponse](../_attachments/apidocs/org/forgerock/openam/auth/node/api/TreeFailureResponse.html) object into your tree hook that adds error details to the message when the `acceptException()` method is run. | | `FailureDetailsTreeHook` | [Set Failure Details node](https://docs.pingidentity.com/auth-node-ref/8/set-failure-details.html) | Adds failure details to the response.You can inject a [TreeFailureResponse](../_attachments/apidocs/org/forgerock/openam/auth/node/api/TreeFailureResponse.html) object into your tree hook that adds failure details to the message when the `acceptFailure()` method is run. | | `SuccessDetailsTreeHook` | [Set Success Details node](https://docs.pingidentity.com/auth-node-ref/8/set-success-details.html) | Adds success details to the response. | | `UpdatePersistentCookieTreeHook` | [Persistent Cookie Decision node](https://docs.pingidentity.com/auth-node-ref/8/persistent-cookie-decision.html) | Recreates the specified persistent cookie with new idle time and JWT `kid` header values. | ## The core class of an authentication tree hook The following example shows an excerpt from the `UpdatePersistentCookieTreehook` class. The Persistent Cookie Decision node uses this tree hook to recreate the persistent cookie. ```java /** * A TreeHook for updating a persistent cookie. */ @TreeHook.Metadata(configClass = PersistentCookieDecisionNode.Config.class) (1) public class UpdatePersistentCookieTreeHook implements TreeHook { (2) ... @Inject (3) UpdatePersistentCookieTreeHook(@Assisted Request request, @Assisted Response response, @Assisted PersistentCookieDecisionNode.Config config, @Assisted Realm realm, PersistentJwtStringSupplier persistentJwtStringSupplier, PersistentCookieResponseHandler persistentCookieResponseHandler, SecretReferenceCache secretReferenceCache){ this.request = request; this.response = response; this.config = config; this.persistentJwtStringSupplier = persistentJwtStringSupplier; this.persistentCookieResponseHandler = persistentCookieResponseHandler; this.secretCache = secretReferenceCache.realm(realm); } @Override public void accept() throws TreeHookException { (4) logger.debug("UpdatePersistentCookieTreeHook.accept"); String orgName = PersistentCookieResponseHandler.getOrgName(response); Cookie originalJwt = getJwtCookie(request, config.persistentCookieName()); if (originalJwt == null) { return; } ... } ... } ``` | | | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | The `@TreeHook.Metadata` annotation. Before defining the core class, use a Java `@TreeHook.Metadata` annotation to specify the class the tree hook uses for its configuration. Use the `configClass` property to specify the configuration class of the node that will be using the tree hook. The node class must invoke ActionBuilder's addSessionHook method to specify the treehook class to be run after a successful login. For example, in the PersistentCookieDecisionNode.class: @Override public Action process(TreeContext context) throws NodeProcessException { ... actionBuilder = actionBuilder .replaceSharedState(context.sharedState.copy().put(USERNAME, userName)) .withUniversalId(identityService.getUniversalId(userName, realm, USER)) .withIdentifiedIdentity(userName, USER) .putSessionProperty(generateSessionPropertyName(config.persistentCookieName()), config.persistentCookieName()) .addSessionHook(UpdatePersistentCookieTreeHook.class, nodeId, getClass().getSimpleName()); ... } | | **2** | The core class must implement the `TreeHook` interface.Learn more in the [TreeHook](../_attachments/apidocs/org/forgerock/openam/auth/node/api/TreeHook.html) interface in the *AM Public API Javadoc*. | | **3** | AM uses Google's *Guice* dependency injection framework for authentication nodes and tree hooks. Use the `@Inject` annotation to construct a new instance of the tree hook, specifying the configuration interface set up earlier and any other required parameters.You can use the `@Assisted` annotation to pass in the following parameters:- [SSOToken](../_attachments/apidocs/com/iplanet/sso/SSOToken.html): The token with details of the session, following a successful authentication. - [Response](../_attachments/apidocs/org/forgerock/http/protocol/Request.html): The response sent to the user on successful authentication. - [Request](../_attachments/apidocs/org/forgerock/http/protocol/Response.html): The authentication request. - [Realm](../_attachments/apidocs/org/forgerock/openam/core/realms/Realm.html): The realm in which authentication is taking place. - `config`: The node configuration object. The type is defined by the `@TreeHook.Metadata` annotation. - [TreeFailureResponse](../_attachments/apidocs/org/forgerock/openam/auth/node/api/TreeFailureResponse.html): An object that contains the failure details for the `acceptFailure()` message and the error details for the `acceptException()` message.Learn more in the [Inject](https://google.github.io/guice/api-docs/latest/javadoc/index.html?com/google/inject/Inject.html) annotation type and the [Assisted](https://google.github.io/guice/api-docs/latest/javadoc/index.html?com/google/inject/assistedinject/Assisted.html) annotation type in the *Google Guice Javadoc*. | | **4** | Implement the `public void accept()` method to define actions to perform on a successful journey outcome.Optionally, override the `void acceptFailure()` or `void acceptException()` methods to define actions to perform on failure or exceptions.The main logic of a tree hook is handled by these two methods. |