mountek

Posted on Nov 11

Enforcing Maker-Checker Approvals in Financial AI Agents: A Hybrid Gateway-Orchestration Topology

#java #ai #security #architecture

As enterprise core banking platforms integrate Large Language Model (LLM) agents to automate operational decisions, governing AI Tool-Calling (Function Calling) has emerged as a primary architectural challenge. When an AI agent generates tool calls to execute REST APIs—such as initiating wire transfers, adjusting credit limits, or waiving fees—the system must enforce strict regulatory controls.

A common design pitfall is confusing Structural Access Control with Stateful Business Process Logic. Attempting to force an Identity and Access Management (IAM) provider like Keycloak to evaluate stateful financial metrics (such as fetching database balances or evaluating $10,000 threshold routing) introduces tight coupling, database latency, and broken execution flows. Throwing a 403 Forbidden error at the gateway for a high-value transaction kills the request entirely, preventing the system from ever instantiating the required human supervisor approval task.

Under the Xenon Architecture Standards, modern core banking platforms govern AI tool-calling through a Hybrid Gateway-Orchestration Topology. Structural capability authorization ("Is this AI agent allowed to invoke the wire transfer tool?") is handled at the perimeter gateway via Keycloak. Stateful context evaluation ("Does a $10,000 transfer require a human supervisor sign-off?") is handled within the durable execution layer via Temporal Sagas and Flowable DMN Engines.

💡 Explore the Xenon Architecture Standard For comprehensive architectural blueprints, BIAN service domain mappings, and dual-orchestration integration patterns, visit the official Xenon Architecture Guide. To inspect reference code, infrastructure templates, and open-source banking modules, explore the VecPay-Tech GitHub Organization.

Architectural Taxonomy: Capability vs. Context Governance

Separating Identity Capability from Business Context establishes clear boundaries across the BIAN (Banking Industry Architecture Network) ecosystem.

Governance Layer	Primary Component	Evaluation Scope	State Requirement	System Action on Positive Match	System Action on Failure / Boundary Match
Structural Capability (Gateway)	Keycloak IAM	Token OAuth2 scopes (`wire:execute`), role claims, identity validity	Stateless (Evaluates JWT claims)	Pass request to API Ingress Gateway	403 Forbidden (Hard stop; blocks malicious calls)
Stateful Context (Orchestration)	Temporal + Flowable DMN	Transaction amounts, stateful balance lookups, DTI ratios	Stateful (Queries core databases & DMN tables)	Execute automated transaction Saga	Suspend & Route (Generate Flowable Checker task)

Mathematical Model: Risk-Driven Workflow Routing

To evaluate whether an AI agent's tool payload requires human intervention, the durable workflow layer calculates a Contextual Risk Index $R_{\text{context}}$ by combining real-time database facts with agent execution metrics:

R_{\text{context}} = w_1 \cdot \left( \frac{\text{Requested-Amount}}{\text{Threshold}{\text{max}}} \right) + w_2 \cdot \bigl( 1 - C{\text{agent}} \bigr) + w_3 \cdot \left( \frac{\text{Requested-Limit}}{\text{Current-Limit}} \right)

Where:

$\text{Requested-Amount}$ is the transaction value normalized against the BIAN domain cap $\text{Threshold}_{\text{max}}$ .
$C_{\text{agent}}$ is the LLM agent's reported confidence score ( $0.0 \le C_{\text{agent}} \le 1.0$ ).
$\text{Current-Limit}$ is fetched statefully from the core database during activity execution.
$w_1, w_2, w_3$ are policy weight vectors such that $\sum w_i = 1.0$ .

If $R_{\text{context}}$ exceeds defined DMN thresholds, Temporal does not fail the execution. It suspends the workflow state, generates a cryptographic approval token, and creates a Flowable Human Checker User Task.

Hybrid System Topology

The system separates perimeter identity validation from stateful business process routing.

                           HYBRID GOVERNANCE ARCHITECTURE

  +---------------------------------------------------------------------------------+
  | PERIMETER GATEWAY LAYER (Stateless Capability Enforcement)                     |
  |                                                                                 |
  |  AI Agent Tool Call ---> [ API Gateway + Keycloak Filter ]                       |
  |                           ├── Missing Scope `wire:write` ──► [ 403 Forbidden ]  |
  |                           └── Has Valid Scope ───────────────► [ PASS ]         |
  +-----------------------------------|---------------------------------------------+
                                      |
                           1. Dispatch Authorized Tool Call
                                      |
                                      v
  +---------------------------------------------------------------------------------+
  | DURABLE ORCHESTRATION LAYER (Stateful Context Execution - Temporal)             |
  |                                                                                 |
  |  [ Start PaymentExecutionWorkflow ]                                             |
  |    ├── Activity: Fetch Stateful DB Balances & Credit Limits                     |
  |    └── Activity: Evaluate Business Rules (Flowable DMN)                         |
  +-----------------------------------|---------------------------------------------+
                                      |
            ┌─────────────────────────┴─────────────────────────┐
            | DMN Decision: AUTO_APPROVE                        | DMN Decision: REQUIRES_CHECKER
            v                                                   v
  +-----------------------------------+               +-----------------------------------+
  | MICROSERVICE SETTLEMENT           |               | FLOWABLE HUMAN WORKFLOW           |
  |                                   |               |                                   |
  | [ Executes Ledger Mutation ]      |               | 1. Create Human Checker Task      |
  +-----------------------------------+               | 2. Temporal Suspends (Awaits Sig) |
                                                      | 3. Human Checker Signs Off        |
                                                      +-----------------+-----------------+
                                                                        |
                                                               4. Send Temporal Signal
                                                                        |
                                                                        v
                                                      +-----------------------------------+
                                                      | MICROSERVICE SETTLEMENT           |
                                                      | [ Executes Ledger Mutation ]      |
                                                      +-----------------------------------+

Technical Implementation

1. Keycloak Gateway Filter (Stateless Capability Check)

This gateway component validates that the calling AI agent possesses the required structural OAuth2 scope (wire:execute) before allowing the request to enter the orchestration mesh.

package com.xenon.banking.gateway.filter;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;
import reactor.core.publisher.Mono;

import java.util.List;

@Component
public class KeycloakCapabilityGatewayFilter implements WebFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String path = exchange.getRequest().getURI().getPath();

        // Target AI tool-calling execution endpoints
        if (path.startsWith("/api/v1/tools/wire-transfer")) {
            List<String> authHeaders = exchange.getRequest().getHeaders().get("Authorization");

            if (authHeaders == null || authHeaders.isEmpty()) {
                exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            }

            // Extract JWT and verify structural capability scope
            String token = authHeaders.get(0).replace("Bearer ", "");
            boolean hasWireScope = extractScopesFromJwt(token).contains("wire:execute");

            if (!hasWireScope) {
                // Structural failure: Hard fast-fail at gateway
                exchange.getResponse().setStatusCode(HttpStatus.FORBIDDEN);
                return exchange.getResponse().setComplete();
            }
        }

        // Structural check passed: Forward request to Temporal Workflow trigger
        return chain.filter(exchange);
    }

    private List<String> extractScopesFromJwt(String jwtToken) {
        // Standard stateless JWT claims parsing logic
        return List.of("wire:execute", "account:read");
    }
}

2. Temporal Workflow (Stateful Business Process & Signal Gateway)

The workflow orchestrates stateful database reads, evaluates dynamic DMN rules, and handles asynchronous human checker approval signals without terminating execution.

package com.xenon.banking.workflow;

import com.xenon.banking.activity.AccountStateActivities;
import com.xenon.banking.activity.BusinessRuleActivities;
import com.xenon.banking.activity.PaymentSettlementActivities;
import com.xenon.banking.model.DmnEvaluationResult;
import com.xenon.banking.model.PaymentExecutionPayload;
import io.temporal.activity.ActivityOptions;
import io.temporal.workflow.Workflow;
import io.temporal.workflow.WorkflowInterface;
import io.temporal.workflow.WorkflowMethod;
import io.temporal.workflow.SignalMethod;

import java.time.Duration;

@WorkflowInterface
public interface PaymentExecutionWorkflow {

    @WorkflowMethod
    void executePayment(PaymentExecutionPayload payload);

    @SignalMethod
    void receiveCheckerApproval(String checkerUserId, String approvalSignature);
}

public class PaymentExecutionWorkflowImpl implements PaymentExecutionWorkflow {

    private final AccountStateActivities accountActivities = Workflow.newActivityStub(
            AccountStateActivities.class,
            ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(5)).build()
    );

    private final BusinessRuleActivities ruleActivities = Workflow.newActivityStub(
            BusinessRuleActivities.class,
            ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(5)).build()
    );

    private final PaymentSettlementActivities settlementActivities = Workflow.newActivityStub(
            PaymentSettlementActivities.class,
            ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(10)).build()
    );

    private boolean checkerApproved = false;
    private String approvingCheckerId;

    @Override
    public void executePayment(PaymentExecutionPayload payload) {

        // 1. Stateful Data Fetching via Temporal Activity (Core DB lookup)
        double currentAccountBalance = accountActivities.fetchCurrentBalance(payload.getSourceAccount());
        String customerRiskTier = accountActivities.fetchCustomerRiskTier(payload.getSourceAccount());

        // 2. Evaluate Dynamic Business Rules via Flowable DMN Engine
        DmnEvaluationResult dmnResult = ruleActivities.evaluatePaymentRules(
                payload.getAmount(),
                currentAccountBalance,
                customerRiskTier,
                payload.getAgentConfidenceScore()
        );

        // 3. Process Execution Path Based on Business Rules
        if ("REQUIRES_CHECKER".equals(dmnResult.getDecision())) {

            // Instantiates Flowable Human Task for Supervisor Review
            String taskId = ruleActivities.createFlowableCheckerTask(
                    payload.getPaymentId(),
                    payload.getAmount(),
                    dmnResult.getReasoning()
            );

            Workflow.getLogger(PaymentExecutionWorkflowImpl.class)
                    .info("Payment " + payload.getPaymentId() + " requires Maker-Checker sign-off. Created Task: " + taskId);

            // Suspend workflow execution and await external Human Approval Signal
            Workflow.await(() -> checkerApproved);

            Workflow.getLogger(PaymentExecutionWorkflowImpl.class)
                    .info("Human Sign-Off received from Checker: " + approvingCheckerId + ". Resuming settlement.");
        }

        // 4. Final Settlement Execution
        settlementActivities.executeSettlement(payload.getPaymentId(), payload.getAmount(), approvingCheckerId);
    }

    @Override
    public void receiveCheckerApproval(String checkerUserId, String approvalSignature) {
        this.checkerApproved = true;
        this.approvingCheckerId = checkerUserId;
    }
}

3. Flowable Human Checker Task Signaling Bridge

When a human supervisor approves the task within the operational dashboard, this service emits a Temporal signal to wake up the suspended workflow.

package com.xenon.banking.bridge;

import io.temporal.client.WorkflowClient;
import org.flowable.engine.TaskService;
import org.springframework.stereotype.Service;

@Service
public class FlowableTemporalBridgeService {

    private final TaskService flowableTaskService;
    private final WorkflowClient temporalWorkflowClient;

    public FlowableTemporalBridgeService(TaskService flowableTaskService, WorkflowClient temporalWorkflowClient) {
        this.flowableTaskService = flowableTaskService;
        this.temporalWorkflowClient = temporalWorkflowClient;
    }

    public void approveCheckerTask(String taskId, String checkerUserId, String cryptographicSignature) {
        // 1. Complete Flowable Task
        var task = flowableTaskService.createTaskQuery().taskId(taskId).singleResult();
        String paymentId = (String) flowableTaskService.getVariable(taskId, "paymentId");

        flowableTaskService.complete(taskId);

        // 2. Signal Temporal Workflow to resume execution
        var workflowStub = temporalWorkflowClient.newWorkflowStub(
                com.xenon.banking.workflow.PaymentExecutionWorkflow.class,
                "PaymentWorkflow-" + paymentId
        );

        // Emit signal directly into Temporal's event history
        workflowStub.receiveCheckerApproval(checkerUserId, cryptographicSignature);
    }
}

Analysis of Architectural Trade-Offs

Analyzing the hybrid architecture highlights how responsibilities are balanced across the stack.

1. Separation of Concerns & System Governance

Keycloak manages IAM scopes, OAuth2 client identities, and role assignments.
Temporal & Flowable DMN handle business logic, stateful database queries, and workflow routing.
Outcome: Security policies remain clean and stateless, while business workflows retain full access to operational context.

2. Dynamic Rule Management

Business parameters (such as lowering an approval threshold from $10,000 to $5,000) are managed inside the Flowable DMN Engine or dynamic configuration services.
Outcome: Rule adjustments take effect instantly without re-deploying microservices or updating Temporal workflow code.

3. Fast-Fail Security Protection

Invalid requests (e.g., an AI agent attempting an unauthorized API call without proper scopes) are blocked at the API Gateway by Keycloak.
Outcome: Malicious or malformed requests fail fast at the perimeter, preventing invalid state entries from polluting Temporal's event store.

4. Enterprise Audit Trails & Compliance

Keycloak logs authentication and token issuance events for IAM auditing.
Temporal maintains an event history recording the complete execution lineage: AI Agent initiated -> DMN evaluated -> Flowable task generated -> Human Checker signed off -> Settlement executed.
Outcome: Provides financial regulators (OCC, EBA, BCBS 239) with proof of non-repudiation and process compliance.

Decoupling structural access control from stateful business process routing establishes a resilient architecture for financial AI agents. Assigning capability validation to Keycloak at the gateway while executing contextual Maker-Checker workflows within Temporal and Flowable DMN allows core banking systems to preserve security perimeter defenses, maintain sub-second operational execution, and meet stringent regulatory requirements across all BIAN service domains.

DEV Community