[
https://issues.apache.org/jira/browse/NIFI-14852?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
David Handermann reassigned NIFI-14852:
---------------------------------------
Assignee: David Handermann
> 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
> Assignee: David Handermann
> Priority: Minor
>
> 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)
