feat(header-finalizer): support multiple headers with same name

docs/content/docs/mechanisms/finalizers.adoc

@@ -41,6 +41,8 @@ Configuration using the `config` property is mandatory. Following properties are
 +
 Enables configuration of arbitrary headers with any values build from available information (See also link:{{< relref "/docs/mechanisms/evaluation_objects.adoc#_templating" >}}[Templating]).
 
+In cases where multiple values are required for a single header name (e.g., impersonation groups in Kubernetes), the `header` finalizer will split newline-separated values into separate headers.
+
 .Header finalizer configuration
 ====
 [source, yaml]
@@ -52,6 +54,10 @@ config:
     X-User-ID: '{{ quote .Subject.ID }}'
     X-User-Email: '{{ index .Subject.Attributes "email" | quote }}'
     Host: '{{ .Request.Header "Host" | quote  }}'
+    Impersonate-Group: |
+      {{- range .Subject.Attributes.groups }}
+      {{ . }}
+      {{- end }}
 ----
 ====
 

internal/rules/mechanisms/finalizers/header_finalizer.go

@@ -17,6 +17,8 @@
 package finalizers
 
 import (
+	"strings"
+
 	"github.com/rs/zerolog"
 
 	"github.com/dadrus/heimdall/internal/app"
@@ -94,7 +96,13 @@ func (f *headerFinalizer) Execute(ctx heimdall.RequestContext, sub *subject.Subj
 
 		logger.Debug().Str("_value", value).Msg("Rendered template")
 
-		ctx.AddHeaderForUpstream(name, value)
+		// Split the rendered value into multiple values if newline-separated
+		values := strings.Split(value, "\n")
+		for _, v := range values {
+			if len(v) != 0 {
+				ctx.AddHeaderForUpstream(name, v)
+			}
+		}
 	}
 
 	return nil

internal/rules/mechanisms/finalizers/header_finalizer_test.go

@@ -332,6 +332,31 @@ headers:
 			assert: func(t *testing.T, err error) {
 				t.Helper()
 
+				require.NoError(t, err)
+			},
+		},
+		"support multiple headers with same name using newlines": {
+			config: []byte(`
+headers:
+  Impersonation-Group: |
+    {{- range .Subject.Attributes.groups }}
+    {{ . }}
+    {{- end }}
+`),
+			configureContext: func(t *testing.T, ctx *mocks.RequestContextMock) {
+				t.Helper()
+
+				ctx.EXPECT().AddHeaderForUpstream("Impersonation-Group", "group1")
+				ctx.EXPECT().AddHeaderForUpstream("Impersonation-Group", "group2")
+				ctx.EXPECT().AddHeaderForUpstream("Impersonation-Group", "group3")
+
+				ctx.EXPECT().Request().Return(&heimdall.Request{})
+				ctx.EXPECT().Outputs().Return(map[string]any{})
+			},
+			subject: &subject.Subject{Attributes: map[string]any{"groups": []string{"group1", "group2", "group3"}}},
+			assert: func(t *testing.T, err error) {
+				t.Helper()
+
 				require.NoError(t, err)
 			},
 		},