Castle Authentication Nodes

Castle helps security teams more quickly discover, investigate and stop malicious activity.

This plugin gives you the ability to use Castle's Risk, Filter and Log APIs which provide risk signals and give you the visibility needed to investigate security and fraud incidents.

See castle.io for more information.

Usage

To deploy these nodes, download the jar from the releases tab on github here. Next, copy the jar into the ../web-container/webapps/openam/WEB-INF/lib directory where AM is deployed. Restart the web container to pick up the new nodes. The nodes will then appear in the authentication trees components palette.

Before you begin

1. Create a Castle account
2. Once you're signed in, go the the Dashboard Settings page to configure the Castle Service with the APP ID and API Secret. Please note your Castle environment - the "Sandbox" one is only suggested for non-production usage.
3. Host our castle-js script. See our NPM package for more details.

Castle Service

This plugin provides a realm-specific Castle Service, where you specify common configuration for Castle nodes.

• API Secret - A secret that will be used for authentication purposes.
• App ID - Castle App ID.
• Profiler URI - Castle Javascript link. We highly suggest you host it yourself.
• Allowlisted Headers - A comma-separated list of strings representing HTTP headers that will get passed to the context object with each call to the Castle API, unless they are denylisted. If not set or empty all headers will be sent.
• Denylisted Headers - A comma-separated list of strings representing HTTP headers that will never get passed to the context object.
• Timeout - An integer that represents the time in milliseconds after which a request fails.
• Base URL - The base endpoint of the Castle API without any relative path.

Quick Start

This repository contains sample trees you can import using AM Treetool.

You can batch-import them with this command:

./amtree.sh -h FORGEROCK_URL -u FORGEROCK_ADMIN -p FORGEROCK_ADMIN_PASSWORD -s -r examples/

Alternatively, you can recreate these tools yourself using the ForgeRock tree editor.

Once you configured the Castle Service and you went through a tree that used one of Castle's API, you should be able to inspect the requests that were sent to Castle in the Castle's Debugger.

Castle Profiler Node

This node tags the AM login page with the Castle JS to collect information about the device being used.

Castle Risk Node

This node makes a request to Castle Risk API to assess user risk.

You can also check our API Reference for more details on the Risk API.

Castle Risk Node Configuration

• Event - The Castle Event type.
• Status - The Castle Event status.
• Mail Attribute - The ForgeRock email attribute.

Castle Filter Node

This node makes a request to Castle's bot detection Filter API to retrieve a policy decision about an action.

You can also check our API Reference for more details on the Filter API.

Castle Filter Node Configuration

• Event - The Castle Event type.
• Status - The Castle Event status.
• Mail Attribute - The ForgeRock email attribute.

Castle Log Node

This node makes a request to Castle's Log API. This is an async API that provides visibility into the actions your users take.

You can check our API Reference for more details on the Log API.

Castle Log Node Configuration

• Event - The Castle Event type.
• Status - The Castle Event status.
• Mail Attribute - The ForgeRock email attribute.

Castle Action Node

This node analyzes the response from the Castle Risk Node and routes to the Allow, Challenge or Deny node outcomes.

Castle Score Node

This node analyzes the response from the Castle Risk Node and checks to see if the risk score is above the configured value.

Castle Score Node Configuration

• Score Threshold - Castle’s APIs return a numerical risk score between zero and one. Low-risk events are scored at or near zero, and high-risk events are scored at or near one.

Castle Signal Node

This node analyzes the response from the Castle Risk Node and checks to see if an individual signal has been returned. These signal correspond to Castle Signals found here.

Castle Signal Node Configuration

• Signal Outcomes - A list of Signals that you would like to check for from a Castle Risk evaluation. When a Signal is added to this list, a new outcome will presented on the node. The node will iterate through the configured Signals until a Reason code is found and will return that outcome. Otherwise the None Triggered outcome will be returned.

Castle Approve Device Node

This node calls the Castle Approve Device API to update the users device with approval. session.

Castle Approve Device Node Configuration

• API Secret - A secret that will be used for authentication purposes.
• Base URL - The base endpoint of the Castle API without any relative path.

Example Flows

Login flows

Registration flows

Password reset flows

Password update flows