Daniel Chaffelson created NIFI-14852:
----------------------------------------
Summary: Declare Bearer Authentication in NiFi Core OpenAPI Spec
Key: NIFI-14852
URL: https://issues.apache.org/jira/browse/NIFI-14852
Project: Apache NiFi
Issue Type: Bug
Components: NiFi API
Affects Versions: 2.5.0
Reporter: Daniel Chaffelson
The OpenAPI specification for the Apache NiFi Core API is missing the required
security scheme definition for its primary authorization method. While the API
correctly enforces that clients must use *HTTP Bearer Authentication* (with a
JWT) for all protected endpoints, the spec does not declare the {{bearerAuth}}
security scheme.
This omission prevents standard OpenAPI client generators from creating clients
that can apply the necessary {{Authorization}} header out-of-the-box, requiring
manual workarounds.
*Problem Details*
In NiFi, the authentication and authorization flow is as follows:
# A client calls {{POST /nifi-api/access/token}} with form parameters
({{{}username{}}}, {{{}password{}}}) to receive a JWT. This endpoint does *not*
use an HTTP authentication scheme like Basic auth.
# For all subsequent API calls to protected endpoints, the client must include
the {{Authorization: Bearer <jwt>}} header.
The current {{openapi.json}} spec for the NiFi API fails to model the second
part of this flow. It is missing:
* *Security Scheme Definition:* There is no entry in
{{components.securitySchemes}} to define the {{bearerAuth}} scheme.
* *Global Security Application:* No global {{security}} block is applied to
indicate that endpoints are, by default, protected by Bearer auth.
*Impact*
This spec incompliance directly impacts any team using OpenAPI-compliant code
generation tools to create clients for the NiFi Server API.
* Generated clients do not automatically add the required {{Authorization:
Bearer <token>}} header to protected API calls.
* Downstream projects, such as {*}NiPyAPI{*}, are forced to implement and
maintain client-side logic to inject this header for every request, rather than
relying on behavior defined by the API specification.
* This creates a maintenance burden and deviates from the best practice of
having a self-describing API contract.
h3. Proposed Solution
To align the OpenAPI specification with the actual API behavior, the following
changes should be made.
*1. Define the Bearer Auth Security Scheme*
Add the {{bearerAuth}} scheme to the {{components.securitySchemes}} object.
{{}}
{code:java}
{code}
{{"components": \{
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
// ... existing components
}}}
{{ }}
*2. Apply Bearer Auth as the Global Default*
Since most endpoints are protected by Bearer auth, this should be set as the
global default at the root of the spec.
{code:java}
"security": [ { "bearerAuth": [] }]
{code}
{{}}
*3. Exclude the Login Endpoint from Global Security*
The form-based login endpoint must be explicitly excluded from the global
Bearer auth requirement. This is done by providing an empty {{security}} array
for that specific operation.
{{}}
{code:java}
"paths": {
"/nifi-api/access/token": {
"post": {
"security": [],
...
}
}
}{code}
{{ }}
h3. Expected Outcome
By implementing these changes, the NiFi Server API specification will become
fully self-descriptive regarding its authorization requirements. OpenAPI client
generators will be able to produce clients that correctly apply the
{{Authorization: Bearer}} header to all protected endpoints without requiring
manual, client-side intervention. This simplifies integration and aligns the
project with OpenAPI best practices.
h3. References
* [OpenAPI Security Scheme
Object|https://spec.openapis.org/oas/v3.0.3#security-scheme-object]
* [RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token
Usage|https://www.rfc-editor.org/rfc/rfc6750]
*Notes*
* The per-operation “security” entries referencing capabilities like “Read -
/flow” are authorization policy descriptors, not HTTP authentication schemes;
they should remain, but they do not replace declaring Bearer in securitySchemes.
* No changes are required for Basic auth because NiFi’s login is form-based
and does not require HTTP Basic, though this could be added as an option to
offer further standards-based options.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
