[nifi] branch main updated: NIFI-9960 Add documentation for Sensitive Dynamic Properties (#6089)

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

andrewmlim pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/nifi.git


The following commit(s) were added to refs/heads/main by this push:
     new 5a2992c243 NIFI-9960 Add documentation for Sensitive Dynamic Properties (#6089)
5a2992c243 is described below

commit 5a2992c243e81724ce13033a9818df28d4c3af95
Author: exceptionfactory <ex...@apache.org>
AuthorDate: Thu Jun 2 07:12:22 2022 -0500

    NIFI-9960 Add documentation for Sensitive Dynamic Properties (#6089)
    
    * NIFI-9960 Added documentation for Sensitive Dynamic Properties
    
    - Updated User Guide with Add Property details
    - Updated Developer Guide with annotation configuration details
    - Updated Document Writer to indicate Supports Sensitive Dynamic Properties status
    
    * NIFI-9960 Adjusted User Guide wording based on feedback
---
 nifi-docs/src/main/asciidoc/developer-guide.adoc   |  34 ++++++++++++++++++---
 .../images/add-property-sensitive-value-dialog.png | Bin 0 -> 15549 bytes
 nifi-docs/src/main/asciidoc/user-guide.adoc        |  15 +++++++--
 .../html/HtmlDocumentationWriter.java              |  16 ++++++++++
 .../html/ProcessorDocumentationWriterTest.java     |   2 ++
 5 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/nifi-docs/src/main/asciidoc/developer-guide.adoc b/nifi-docs/src/main/asciidoc/developer-guide.adoc
index a136e149a5..d654a7a77a 100644
--- a/nifi-docs/src/main/asciidoc/developer-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/developer-guide.adoc
@@ -326,21 +326,47 @@ instance of the `PropertyDescriptor.Builder` object,
 calling the appropriate methods on the builder, and finally calling
 the `build` method.
 
-While this method covers most of the use cases, it is sometimes
+===== Dynamic Processor Properties
+
+In addition to standard properties, it is sometimes
 desirable to allow users to configure
-additional properties whose name are not known. This can be achieved
-by overriding the
+additional properties whose names are not predefined.
+This can be achieved by overriding the
 `getSupportedDynamicPropertyDescriptor` method. This method takes a
 `String` as its only argument, which
 indicates the name of the property. The method returns a
 `PropertyDescriptor` object that can be used to validate
 both the name of the property, as well as the value. Any
 PropertyDescriptor that is returned from this method
-should be built setting the value of `isDynamic` to true in the
+should be built setting the value of `isDynamic` to `true` in the
 `PropertyDescriptor.Builder` class. The default
 behavior of AbstractProcessor is to not allow any dynamically created
 properties.
 
+===== Sensitive Dynamic Properties
+
+The default implementation for dynamic properties does not treat the
+property values as sensitive. This approach is sufficient when configuring
+features such as FlowFile attributes or custom expressions, but it does
+not provide protection for values such as passwords or keys.
+
+NiFi 1.17.0 introduced framework support for sensitive dynamic properties
+through a new behavior annotation named `SupportsSensitiveDynamicProperties`.
+The annotation can be applied to a Processor, Controller Service, or
+Reporting Task that supports dynamic properties through the
+`getSupportedDynamicPropertyDescriptor` method. The annotation indicates
+that the component allows individual dynamic properties to be marked as
+sensitive for the purpose of persistence and framework processing.
+
+The `getSupportedDynamicPropertyDescriptor` must return a `PropertyDescriptor`
+with the `sensitive` field set to `false` to allow customization of sensitive
+status. Setting the `sensitive` field to `true` in this method forces all
+dynamic properties to be handled as sensitive. This approach allows sensitive
+status to be upgraded in supported components, but not downgraded.
+
+Secure handling of sensitive property values is the responsibility of the
+annotated class. Components that support sensitive dynamic properties must
+not log property values or provide property values as FlowFile attributes.
 
 ==== Validating Processor Properties
 
diff --git a/nifi-docs/src/main/asciidoc/images/add-property-sensitive-value-dialog.png b/nifi-docs/src/main/asciidoc/images/add-property-sensitive-value-dialog.png
new file mode 100644
index 0000000000..6bdf906064
Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/add-property-sensitive-value-dialog.png differ
diff --git a/nifi-docs/src/main/asciidoc/user-guide.adoc b/nifi-docs/src/main/asciidoc/user-guide.adoc
index 9b6286b40f..2dbc063db6 100644
--- a/nifi-docs/src/main/asciidoc/user-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/user-guide.adoc
@@ -690,8 +690,19 @@ image::edit-property-dropdown.png["Edit Property with Dropdown"]
 
 In the top-right corner of the tab is a button for adding a New Property. Clicking this button will provide the DFM with a dialog to
 enter the name and value of a new property. Not all Processors allow User-Defined properties. In processors that do not allow them,
-the Processor becomes invalid when User-Defined properties are applied. RouteOnAttribute, however, does allow User-Defined properties.
-In fact, this Processor will not be valid until the user has added a property.
+the Processor becomes invalid when User-Defined properties are applied.
+
+Selected Processors support configurable Sensitive Value status for User-Defined properties. Processors must indicate
+support for configurable Sensitive Value status, otherwise the Sensitive Value selection will be disabled in the
+Add Property dialog.
+
+image:add-property-sensitive-value-dialog.png["Add Property with Sensitive Value status"]
+
+Selecting `Yes` for the Sensitive Value setting instructs NiFi to handle the property value as
+sensitive for configuration persistence and framework operations. NiFi encrypts Sensitive Values when storing the flow
+configuration and does not include Sensitive Values in exported Flow Definitions.
+
+RouteOnAttribute allows User-Defined properties and will not be valid until the user has added a property.
 
 image:edit-property-textarea.png["Edit Property with Text Area"]
 
diff --git a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
index 8464143ce1..7ae0eea21d 100644
--- a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
+++ b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
@@ -23,6 +23,7 @@ import org.apache.nifi.annotation.behavior.InputRequirement.Requirement;
 import org.apache.nifi.annotation.behavior.Restricted;
 import org.apache.nifi.annotation.behavior.Restriction;
 import org.apache.nifi.annotation.behavior.Stateful;
+import org.apache.nifi.annotation.behavior.SupportsSensitiveDynamicProperties;
 import org.apache.nifi.annotation.behavior.SystemResourceConsideration;
 import org.apache.nifi.annotation.documentation.CapabilityDescription;
 import org.apache.nifi.annotation.documentation.DeprecationNotice;
@@ -685,6 +686,9 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
 
         if (dynamicProperties != null && dynamicProperties.size() > 0) {
             writeSimpleElement(xmlStreamWriter, "h3", "Dynamic Properties: ");
+
+            writeSupportsSensitiveDynamicProperties(configurableComponent, xmlStreamWriter);
+
             xmlStreamWriter.writeStartElement("p");
             xmlStreamWriter
                     .writeCharacters("Dynamic Properties allow the user to specify both the name and value of a property.");
@@ -736,6 +740,18 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
         }
     }
 
+    private void writeSupportsSensitiveDynamicProperties(final ConfigurableComponent configurableComponent, final XMLStreamWriter writer) throws XMLStreamException {
+        final boolean supportsSensitiveDynamicProperties = configurableComponent.getClass().isAnnotationPresent(SupportsSensitiveDynamicProperties.class);
+        final String sensitiveDynamicPropertiesLabel = supportsSensitiveDynamicProperties ? "Yes" : "No";
+
+        writer.writeStartElement("p");
+
+        writer.writeCharacters("Supports Sensitive Dynamic Properties: ");
+        writeSimpleElement(writer, "strong", sensitiveDynamicPropertiesLabel);
+
+        writer.writeEndElement();
+    }
+
     private List<DynamicProperty> getDynamicProperties(ConfigurableComponent configurableComponent) {
         final List<DynamicProperty> dynamicProperties = new ArrayList<>();
         final DynamicProperties dynProps = configurableComponent.getClass().getAnnotation(DynamicProperties.class);
diff --git a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/html/ProcessorDocumentationWriterTest.java b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/html/ProcessorDocumentationWriterTest.java
index 573cd0c41c..617de73d67 100644
--- a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/html/ProcessorDocumentationWriterTest.java
+++ b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/html/ProcessorDocumentationWriterTest.java
@@ -97,6 +97,8 @@ public class ProcessorDocumentationWriterTest {
         // verify dynamic properties
         assertContains(results, "Routes FlowFiles to relationships based on XPath");
 
+        assertContains(results, "Supports Sensitive Dynamic Properties: <strong>No</strong>");
+
         // input requirement
         assertContains(results, "This component does not allow an incoming relationship.");