A self-contained REST API gateway for Apache NiFi. The RestApiGatewayProcessor embeds a Jetty HTTP server with route-based dispatching, per-route JWT authorization, and RFC 9457 error responses, replacing multi-processor gateway patterns with a single node.
The project also includes a MultiIssuerJWTTokenAuthenticator for FlowFile-based JWT validation (see MultiIssuerJWTTokenAuthenticator Guide). Both processors share JWT validation through a common JwtIssuerConfigService Controller Service supporting multiple identity providers (Keycloak, Entra ID, Auth0) with automatic JWKS key rotation and caching.
Building a REST API gateway in NiFi manually requires chaining HandleHttpRequest + custom validation + HandleHttpResponse with complex error routing.
Adding JWT authentication on top means even more processors, relationships, and configuration, all for what should be a single concern.
The RestApiGatewayProcessor is a single processor that embeds an HTTP server, authenticates and authorizes requests per-route, and converts them into FlowFiles.
Key capabilities:
-
Route-based dispatching: define routes via dynamic properties, each with its own HTTP methods and path patterns
-
Per-route JWT authorization: require specific roles for individual routes
-
RFC 9457 error responses: standardized problem details for authentication and authorization failures
-
Management endpoints:
/metrics(Prometheus-compatible) and/health
Routes can enable async request tracking for POST/PUT/PATCH requests.
Both modes require a DistributedMapCacheClient Controller Service.
-
Simple (
tracking-mode=simple):202withtraceIdand/statuspolling link -
Attachments (
tracking-mode=attachments): adds an/attachments/{traceId}upload endpoint; the parent request waits for attachments (or timeout), then the window closes (409). See Attachment Merge Guide.
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.
-
Download both
nifi-cuioss-api-nar-<version>.narandnifi-cuioss-nar-<version>.narfrom GitHub Releases or Maven Central. -
Copy both NARs into your NiFi extensions directory:
cp nifi-cuioss-api-nar-*.nar nifi-cuioss-nar-*.nar $NIFI_HOME/extensions/
-
Restart NiFi (or wait for NiFi’s auto-detection if configured).
-
The processors MultiIssuerJWTTokenAuthenticator and RestApiGatewayProcessor appear in the "Add Processor" dialog under the tags
jwtandauthentication.
Both processors can be configured through three methods (highest precedence first):
-
NiFi UI: interactive configuration with built-in JWKS validation and token testing
-
Environment variables: for container orchestration (Kubernetes, Docker)
-
Static configuration files: for automated / container deployments
See the Quick Start Guide for a step-by-step walkthrough covering processor properties, issuer configuration, routes, relationships, and the custom UI. For static configuration files and environment variables, see the Configuration Reference.
A local sandbox spins up NiFi and Keycloak in Docker so you can explore both processors with a real identity provider.
./integration-testing/src/main/docker/run-and-deploy.shThe script builds the NAR, copies it into the deployment directory, and starts the containers. NiFi takes about 60-80 seconds to become healthy.
| Service | URL | Credentials |
|---|---|---|
NiFi |
|
|
Keycloak |
|
After code changes, redeploy NiFi without restarting Keycloak:
./integration-testing/src/main/docker/redeploy-nifi.shStop the sandbox:
cd integration-testing/src/main/docker && docker compose down -vThe sandbox includes a pre-configured NiFi flow (flow.json) with a RestApiGatewayProcessor on port 9443 featuring multi-route JWT authorization via Keycloak, RFC 9457 error responses, and a /metrics management endpoint.
The flow also contains a MultiIssuerJWTTokenAuthenticator-based endpoint on port 7777 (see MultiIssuerJWTTokenAuthenticator Guide).
| Module | Purpose |
|---|---|
Controller Service API types ( |
|
NiFi Archive (NAR) for the API: required by NiFi 2.x classloader separation |
|
Shared JWT infrastructure: Controller Service implementation, configuration, utilities |
|
|
|
|
|
Unified Custom UI serving both processors: issuer configuration, token verification, endpoint configuration, metrics |
|
NiFi Archive (NAR): the main deployable artifact bundling processors + UI |
|
Docker-based test environment (NiFi + Keycloak) |
|
Playwright E2E and WCAG accessibility tests |
-
Architecture Overview: module overview, "which processor" decision guide
-
Gateway Architecture: pipeline, auth layers, metrics, error handling
-
JWT Processor Architecture: flow, attributes, OAuth-Sheriff lifecycle
-
Standards Compliance: RFC/standards compliance table
-
Quick Start Guide: RestApiGateway setup in under 5 minutes
-
MultiIssuerJWTTokenAuthenticator Guide: FlowFile-based JWT validation with integration test flow
-
Issuer Configuration Walkthrough: step-by-step UI configuration with test environment and troubleshooting
-
Attachment Merge Guide: Wait/Notify synchronization for parent requests with attachments
-
Building Guide: build, code quality, SonarQube, integration and E2E tests
-
Configuration Reference: all property tables, static config, environment variables
-
Error Reference (RFC 9457): consolidated error types returned by the gateway
-
Integration Testing Environment: Docker setup with NiFi and Keycloak
-
End-to-End Testing: Playwright tests for processor UI and WCAG compliance
See the Building Guide for build commands, code quality checks, SonarQube analysis, and integration/E2E test instructions.