From bf54e020a9ced8d4eba8695de7277584dc01a144 Mon Sep 17 00:00:00 2001 From: Jameria Self <73364088+jself-sudoku@users.noreply.github.com> Date: Fri, 7 Nov 2025 11:07:52 -0500 Subject: [PATCH] AAP-54293 Update the documentation on Headers for event streams (#4955) * AAP-54293 Add new content on HTTP headers in event streams * AAP-54293 Correct alignment of sub-chapters for HTTP headers * AAP-54293 Updates to content based on SME review and comments * AAP-54293 Removed the event filtering and routing feature from HTTP headers description, per SME * AAP-54293 Removed the event filtering and routing content --- .../assembly-simplified-event-routing.adoc | 4 ++++ .../modules/eda/con-eda-http-headers.adoc | 22 +++++++++++++++++++ .../eda/proc-eda-configure-http-headers.adoc | 20 +++++++++++++++++ .../eda/proc-eda-create-event-stream.adoc | 9 ++++++-- 4 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 downstream/modules/eda/con-eda-http-headers.adoc create mode 100644 downstream/modules/eda/proc-eda-configure-http-headers.adoc diff --git a/downstream/assemblies/eda/assembly-simplified-event-routing.adoc b/downstream/assemblies/eda/assembly-simplified-event-routing.adoc index 1b263903e5..62bc14b926 100644 --- a/downstream/assemblies/eda/assembly-simplified-event-routing.adoc +++ b/downstream/assemblies/eda/assembly-simplified-event-routing.adoc @@ -14,6 +14,10 @@ include::eda/proc-eda-create-event-stream-credential.adoc[leveloffset=+1] include::eda/proc-eda-create-event-stream.adoc[leveloffset=+1] +include::eda/con-eda-http-headers.adoc[leveloffset=+1] + +include::eda/proc-eda-configure-http-headers.adoc[leveloffset=+2] + include::eda/proc-eda-config-remote-sys-to-events.adoc[leveloffset=+1] include::eda/proc-eda-verify-event-streams-work.adoc[leveloffset=+1] diff --git a/downstream/modules/eda/con-eda-http-headers.adoc b/downstream/modules/eda/con-eda-http-headers.adoc new file mode 100644 index 0000000000..6f5a8030f7 --- /dev/null +++ b/downstream/modules/eda/con-eda-http-headers.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: CONCEPT + +[id="eda-http-headers"] + += HTTP headers + +[role="_abstract"] +In the context of {EDAName} and event streams, HTTP headers play a significant role because they carry the necessary context and security information about the incoming event from a third-party source (for example, GitHub, a monitoring tool, or a proprietary webhook). They include the following capabilities: + +Authentication and non-repudiation:: +This is the most critical use. Headers often contain tokens, API keys, or security signatures (like an HMAC in an `X-Hub-Signature` header) that {EDAName} uses to _verify the sender's identity_ and ensure the event payload has not been tampered with. This supports non-repudiation—proof that the event came from a legitimate source. + +Debugging and Logging:: +Headers provide crucial data points (`Date`, `User-Agent`, `X-Request-ID`) for tracing the event's path, helping system administrators and SREs _debug_ issues related to delayed or failed event processing. + +Headers are essential for all HTTP communication, serving several distinct purposes: + +* *Context and metadata:* Describe the data being sent (for example, `Content-Type: application/json, Content-Length: 1024`). +* *Client/Server Capabilities:* Inform the receiving party of the sender's capabilities or preferences (for example, `Accept-Language: en-US`). +* *Authentication/Authorization:* Carry security credentials (for example, `Authorization: Bearer `). +* *Caching:* Controls how content should be cached by clients and proxies (for example, `Cache-Control: max-age=3600`). +* *Routing and Tracking:* They facilitate network routing and transaction tracking, often via custom headers (for example, `X-Request-ID`). \ No newline at end of file diff --git a/downstream/modules/eda/proc-eda-configure-http-headers.adoc b/downstream/modules/eda/proc-eda-configure-http-headers.adoc new file mode 100644 index 0000000000..399dfd09c3 --- /dev/null +++ b/downstream/modules/eda/proc-eda-configure-http-headers.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: PROCEDURE +[id="eda-configure-http-headers"] + += Configuring HTTP headers securely for event streams + +[role="_abstract"] +To enhance event stream security, you must explicitly define which HTTP headers are passed. These headers carry the critical context and authentication data required for processing. + +.Procedure + +. To include all HTTP headers, enter an asterisk (*) in the Headers field. This allows all HTTP headers with the exception of a few headers: +* *Excluded:* Headers that begin with `X-Envoy`, `X-Trusted-Proxy`, `X-Forwarded-For`, and `X-Real-Id` +* *Redacted:* Authorization header (for example, `Authorization: Redacted`) ++ +[IMPORTANT] +==== +If the *Headers* field is empty, none of the HTTP headers will be added to the event payload in Production and Test mode. +==== ++ +. To include a specific set of HTTP headers, enter the names of the desired headers as a comma-delimited string (for example, `Host,Authorization,X-Request-ID`). diff --git a/downstream/modules/eda/proc-eda-create-event-stream.adoc b/downstream/modules/eda/proc-eda-create-event-stream.adoc index f8affc88b9..2ca6a20a77 100644 --- a/downstream/modules/eda/proc-eda-create-event-stream.adoc +++ b/downstream/modules/eda/proc-eda-create-event-stream.adoc @@ -27,8 +27,13 @@ Event stream type:: Select the event stream type you prefer. This list displays at least 10 default event stream types that can be used to authenticate the connection coming from your remote server. ==== Credentials:: Select a credential from the list, preferably the one you created for your event stream. -Headers:: Enter HTTP header keys, separated by commas, that you want to include in the event payload. To include all headers, leave the field empty. - +Headers:: Enter HTTP header keys, separated by commas, that you want to include in the event payload. ++ +[IMPORTANT] +==== +If your automation relies on HTTP headers being present in the event payload, you must explicitly define them to avoid unintentional exposure of sensitive information. For more information about HTTP headers and how to securely configure them, see link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_decisions/simplified-event-routing#eda-http-headers[HTTP headers] and link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_decisions/simplified-event-routing#eda-configure-http-headers[Configuring HTTP headers securely for event streams]. +==== ++ Forward events to rulebook activation:: Use this option to enable or disable the capability of forwarding events to rulebook activations. + [NOTE]