feat: add correlation ID infrastructure for SAML flow log tracing

Introduces three new components to address issue #1971:

- CorrelationId: shared mutable DI service (get/set) that acts as a
  per-request holder for the active correlation ID
- CorrelationIdRepository: Symfony service backed by the session with
  three operations:
    mint(requestId)  — generate a random ID for an SP request (idempotent)
    link(target, src) — copy the ID to an IdP request ID
    resolve(requestId) — push the stored ID into CorrelationId
  Safely no-ops when no session is available (CLI, unit tests).
- CorrelationIdProcessor: Monolog processor that stamps correlation_id
  on every log record from the shared CorrelationId service

DI wiring: services.yml registers CorrelationId and CorrelationIdRepository
(with @request_stack); logging.yml registers the Monolog processor.

Author: kayjoosten

config/services/logging.yml

@@ -30,6 +30,12 @@ services:
         tags:
             - { name: monolog.processor }
 
+    OpenConext\EngineBlock\Logger\Processor\CorrelationIdProcessor:
+        arguments:
+            - '@OpenConext\EngineBlock\Request\CorrelationId'
+        tags:
+            - { name: monolog.processor }
+
     OpenConext\EngineBlock\Logger\Processor\SessionIdProcessor:
         tags:
             - { name: monolog.processor }

config/services/services.yml

@@ -56,6 +56,15 @@ services:
             - '@OpenConext\EngineBlock\Request\UniqidGenerator'
         public: true
 
+    OpenConext\EngineBlock\Request\CorrelationId:
+        public: true
+
+    OpenConext\EngineBlock\Request\CorrelationIdRepository:
+        public: true
+        arguments:
+            - '@OpenConext\EngineBlock\Request\CorrelationId'
+            - '@request_stack'
+
     OpenConext\EngineBlockBundle\Security\Http\EntryPoint\JsonBasicAuthenticationEntryPoint:
         arguments:
             - 'engine-api.%domain%'

src/OpenConext/EngineBlock/Logger/Processor/CorrelationIdProcessor.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * Copyright 2010 SURFnet B.V.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace OpenConext\EngineBlock\Logger\Processor;
+
+use Monolog\LogRecord;
+use Monolog\Processor\ProcessorInterface;
+use OpenConext\EngineBlock\Request\CorrelationId;
+
+final class CorrelationIdProcessor implements ProcessorInterface
+{
+    public function __construct(private readonly CorrelationId $correlationId)
+    {
+    }
+
+    public function __invoke(LogRecord $record): LogRecord
+    {
+        $record->extra['correlation_id'] = $this->correlationId->get();
+
+        return $record;
+    }
+}

src/OpenConext/EngineBlock/Request/CorrelationId.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * Copyright 2010 SURFnet B.V.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace OpenConext\EngineBlock\Request;
+
+final class CorrelationId
+{
+    private ?string $correlationId = null;
+
+    public function get(): ?string
+    {
+        return $this->correlationId;
+    }
+
+    public function set(string $correlationId): void
+    {
+        $this->correlationId = $correlationId;
+    }
+}

src/OpenConext/EngineBlock/Request/CorrelationIdRepository.php

@@ -0,0 +1,115 @@
+<?php
+
+/**
+ * Copyright 2010 SURFnet B.V.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace OpenConext\EngineBlock\Request;
+
+use Symfony\Component\HttpFoundation\Exception\SessionNotFoundException;
+use Symfony\Component\HttpFoundation\RequestStack;
+
+/**
+ * Symfony service that owns all three correlation ID session operations:
+ *
+ *  mint()    — generate a new ID for a SAML request (back-button safe)
+ *  link()    — copy an existing ID to a new SAML request ID (SP→IdP handoff)
+ *  resolve() — look up the ID and push it into the CorrelationId value holder
+ *
+ * Uses the Symfony session bag under the key 'CorrelationIds'.
+ * Registered as a shared service so it is instantiated once per HTTP request.
+ *
+ * Note: session entries are never explicitly evicted after a flow completes.
+ * Each authentication adds up to two entries (SP + IdP request ID). This is
+ * intentional and consistent with AuthnRequestSessionRepository's behaviour;
+ * SAML sessions are short-lived so unbounded growth is not a concern in practice.
+ */
+final class CorrelationIdRepository
+{
+    private const SESSION_KEY = 'CorrelationIds';
+
+    public function __construct(
+        private readonly CorrelationId $correlationId,
+        private readonly RequestStack $requestStack,
+    ) {
+    }
+
+    /**
+     * Generates and stores a correlation ID for $requestId if none exists yet.
+     * Safe to call multiple times for the same ID (back-button guard).
+     */
+    public function mint(string $requestId): void
+    {
+        try {
+            $session = $this->requestStack->getSession();
+        } catch (SessionNotFoundException) {
+            return;
+        }
+
+        $ids = $session->get(self::SESSION_KEY, []);
+
+        if (!isset($ids[$requestId])) {
+            $ids[$requestId] = bin2hex(random_bytes(16));
+            $session->set(self::SESSION_KEY, $ids);
+        }
+    }
+
+    /**
+     * Copies the correlation ID from $sourceRequestId to $targetRequestId.
+     * Called when EngineBlock creates its own AuthnRequest to send to the IdP,
+     * so that the IdP leg can be traced back to the original SP flow.
+     */
+    public function link(string $targetRequestId, string $sourceRequestId): void
+    {
+        try {
+            $session = $this->requestStack->getSession();
+        } catch (SessionNotFoundException) {
+            return;
+        }
+
+        $ids = $session->get(self::SESSION_KEY, []);
+
+        if (!array_key_exists($sourceRequestId, $ids)) {
+            return;
+        }
+
+        $ids[$targetRequestId] = $ids[$sourceRequestId];
+        $session->set(self::SESSION_KEY, $ids);
+    }
+
+    /**
+     * Looks up the correlation ID for $requestId and pushes it into the
+     * CorrelationId DI service so all subsequent log entries carry it.
+     * No-op when $requestId is null or not found.
+     */
+    public function resolve(?string $requestId): void
+    {
+        if ($requestId === null) {
+            return;
+        }
+
+        try {
+            $session = $this->requestStack->getSession();
+        } catch (SessionNotFoundException) {
+            return;
+        }
+
+        $cid = $session->get(self::SESSION_KEY, [])[$requestId] ?? null;
+
+        if ($cid !== null) {
+            $this->correlationId->set($cid);
+        }
+    }
+}

tests/unit/OpenConext/EngineBlock/Logger/Processor/CorrelationIdProcessorTest.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * Copyright 2010 SURFnet B.V.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace OpenConext\EngineBlock\Logger\Processor;
+
+use DateTimeImmutable;
+use Monolog\Level;
+use Monolog\LogRecord;
+use OpenConext\EngineBlock\Request\CorrelationId;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+class CorrelationIdProcessorTest extends TestCase
+{
+    #[Group('EngineBlock')]
+    #[Group('Logger')]
+    #[Test]
+    public function correlation_id_is_added_to_the_record()
+    {
+        $correlationId = new CorrelationId();
+        $correlationId->set('test-correlation-id');
+
+        $processor = new CorrelationIdProcessor($correlationId);
+        $record = new LogRecord(
+            datetime: new DateTimeImmutable(),
+            channel: 'test',
+            level: Level::Debug,
+            message: 'test message',
+            context: [],
+            extra: [],
+        );
+
+        $processedRecord = ($processor)($record);
+
+        $this->assertEquals('test-correlation-id', $processedRecord->extra['correlation_id']);
+    }
+
+    #[Group('EngineBlock')]
+    #[Group('Logger')]
+    #[Test]
+    public function correlation_id_is_null_when_not_set()
+    {
+        $correlationId = new CorrelationId();
+
+        $processor = new CorrelationIdProcessor($correlationId);
+        $record = new LogRecord(
+            datetime: new DateTimeImmutable(),
+            channel: 'test',
+            level: Level::Debug,
+            message: 'test message',
+            context: [],
+            extra: [],
+        );
+
+        $processedRecord = ($processor)($record);
+
+        $this->assertNull($processedRecord->extra['correlation_id']);
+    }
+}