NiFi JWT Authentication Processor

Table of Contents

• What is it?
• The Problem
• The Solution
• Installation
  • From a Release
  • From Source
  • Docker / Kubernetes
• Configuration
  • Working Example: Integration Test Flow
• Components
• Documentation
  • Specifications
  • Guides
  • Testing
  • Development
• Building
  • Code Quality
  • Integration & E2E Tests

What is it?

A custom Apache NiFi processor that validates JWT tokens against multiple identity providers in a single flow. It validates JWT signatures, checks expiration and audience claims, and supports multiple identity providers (e.g. Keycloak, Entra ID, Auth0) simultaneously — with automatic JWKS key rotation and caching.

The Problem

NiFi flows that consume REST APIs or process webhook payloads often receive JWT-authenticated requests. Out of the box, NiFi has no processor to validate these tokens. This forces teams to either:

• write custom scripts inside ExecuteScript processors with no key rotation or caching,

• call an external validation service, adding latency and a point of failure, or

• skip token validation entirely and trust the upstream reverse proxy.

The Solution

This processor drops into any NiFi flow as a single node. It reads the JWT from a FlowFile attribute, validates it against one or more JWKS endpoints via a shared Controller Service, and writes the token claims as FlowFile attributes — ready for downstream routing and processing.

Installation

You need two NAR files (NiFi Archives):

• nifi-cuioss-api-nar — Controller Service API interfaces (required by NiFi 2.x classloader separation)

• nifi-cuioss-nar — Processors, Controller Service implementation, configuration UI, and all dependencies

NiFi 2.x requires that Controller Service API interfaces reside in a separate NAR from their implementations. Both NARs must be deployed together.

From a Release

1. Download both nifi-cuioss-api-nar-<version>.nar and nifi-cuioss-nar-<version>.nar from GitHub Releases or Maven Central.

2. Copy both NARs into your NiFi extensions directory:

   cp nifi-cuioss-api-nar-*.nar nifi-cuioss-nar-*.nar $NIFI_HOME/extensions/

3. Restart NiFi (or wait for NiFi’s auto-detection if configured).

4. The processor MultiIssuerJWTTokenAuthenticator appears in the "Add Processor" dialog under the tags jwt, oauth, authentication.

From Source

git clone https://github.com/cuioss/nifi-extensions.git
cd nifi-extensions
./mvnw clean install -DskipTests
cp nifi-cuioss-api-nar/target/nifi-cuioss-api-nar-*.nar \
   nifi-cuioss-nar/target/nifi-cuioss-nar-*.nar \
   $NIFI_HOME/extensions/

Docker / Kubernetes

Mount or copy both NARs into the container’s extensions directory:

# Docker Compose example
services:
  nifi:
    image: apache/nifi:2.7.2
    volumes:
      - ./nars/:/opt/nifi/nifi-current/extensions/:ro

The nars/ directory must contain both nifi-cuioss-api-nar-<version>.nar and nifi-cuioss-nar-<version>.nar.

Configuration

The processor can be configured through three methods (in order of precedence):

1. Static configuration files — for automated / container deployments

2. Environment variables — for container orchestration (Kubernetes, Docker)

3. NiFi UI — interactive configuration with built-in JWKS validation and token testing

See the Quick Start Guide for a step-by-step walkthrough covering processor properties, issuer configuration, relationships, output attributes, static files, and environment variables.

Working Example: Integration Test Flow

The integration tests include a complete NiFi flow definition that demonstrates the processor in action with a real Keycloak identity provider. The flow is defined in flow.json and implements a JWT authentication gateway:

• HandleHttpRequest accepts incoming HTTP on port 7777

• MultiIssuerJWTTokenAuthenticator validates the JWT and checks roles

• Authorized requests (HTTP 200) and rejected requests (HTTP 401) are routed through separate paths

• Response bodies contain the jwt.* attributes as JSON for inspection

The authenticator is configured with one Keycloak issuer:

issuer.keycloak.jwks-url = http://keycloak:8080/realms/oauth_integration_tests/protocol/openid-connect/certs
issuer.keycloak.issuer    = http://keycloak:8080/realms/oauth_integration_tests
issuer.keycloak.required-roles = read

To run the full integration test suite locally:

./mvnw verify -Pintegration-tests

See Flow Pipeline Design for the complete pipeline architecture and test scenarios.

Components

Module	Purpose
nifi-cuioss-api	Controller Service API interfaces (JwtIssuerConfigService, JwtAuthenticationConfig)
nifi-cuioss-api-nar	NiFi Archive (NAR) for the API — required by NiFi 2.x classloader separation
nifi-cuioss-common	Shared JWT infrastructure: Controller Service implementation, configuration, utilities
nifi-cuioss-processors	JWT processor implementation
nifi-cuioss-ui	Custom NiFi UI with JWKS validation, token verification, and metrics tabs
nifi-cuioss-nar	NiFi Archive (NAR) — the main deployable artifact bundling processors + UI
integration-testing	Docker-based test environment (NiFi + Keycloak)
e-2-e-playwright	Playwright E2E and WCAG accessibility tests

Documentation

Specifications

• Requirements

• Specification

• Configuration Reference

• Static Configuration & Container Deployment

• UI Configuration

• Security

• Token Validation

• Technical Components

Guides

• Quick Start Guide — get running in under 5 minutes

• Issuer Configuration Walkthrough — step-by-step UI configuration with test environment and troubleshooting

Testing

• Integration Testing Environment — Docker setup with NiFi and Keycloak

• End-to-End Testing — Playwright tests for processor UI and WCAG compliance

• Accessibility Testing Guide

Development

• Error Handling

• Internationalization

• Observability & Metrics

• Log Messages Reference

Building

./mvnw clean install                    # Full build with tests
./mvnw clean install -DskipTests        # Build without tests

Code Quality

./mvnw -Ppre-commit clean install -DskipTests   # Pre-commit quality checks
./mvnw clean verify -Psonar                      # SonarQube analysis

This project follows centralized coding standards from cui-llm-rules covering Java, JavaScript, testing, and documentation.

Integration & E2E Tests

# Start Docker test environment (NiFi + Keycloak)
./integration-testing/src/main/docker/run-and-deploy.sh

# Run integration tests via Maven
./mvnw verify -Pintegration-tests

# Run Playwright E2E tests directly
cd e-2-e-playwright && npm run playwright:test

See Integration Testing and E2E Testing for detailed instructions.