Add SAML traffic recorder to compare EngineBlock output between commits

config/services_ci.yaml

@@ -73,6 +73,10 @@ services:
             $logFile: '/tmp/eb-fixtures/log-records.ndjson'
         tags: ['fob.context']
 
+    OpenConext\EngineBlockFunctionalTestingBundle\Saml2\Recording\SamlTrafficRecorder:
+
+    OpenConext\EngineBlockFunctionalTestingBundle\Command\NormalizeSamlRecordingCommand:
+
     OpenConext\EngineBlockFunctionalTestingBundle\Fixtures\SbsClientStateManager:
         arguments:
             - "@engineblock.functional_testing.data_store.sbs_client_state_mananger"

src/OpenConext/EngineBlockFunctionalTestingBundle/Command/NormalizeSamlRecordingCommand.php

@@ -0,0 +1,92 @@
+<?php
+
+/**
+ * Copyright 2026 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.
+ */
+
+declare(strict_types=1);
+
+namespace OpenConext\EngineBlockFunctionalTestingBundle\Command;
+
+use InvalidArgumentException;
+use OpenConext\EngineBlockFunctionalTestingBundle\Saml2\Recording\SamlXmlNormalizer;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(
+    name: 'engineblock:saml:normalize-recording',
+    description: 'Normalize SAML messages recorded during a Behat run so two runs can be compared with diff'
+)]
+final class NormalizeSamlRecordingCommand extends Command
+{
+    protected function configure(): void
+    {
+        $this
+            ->addArgument('source', InputArgument::REQUIRED, 'Directory written by the recorder (EB_SAML_RECORD_DIR)')
+            ->addArgument('target', InputArgument::REQUIRED, 'Directory to write the normalized dumps to');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $source = rtrim((string) $input->getArgument('source'), '/');
+        $target = rtrim((string) $input->getArgument('target'), '/');
+
+        if (!is_dir($source)) {
+            $output->writeln(sprintf('<error>Source directory "%s" does not exist</error>', $source));
+            return Command::FAILURE;
+        }
+
+        $scenarios = 0;
+        $messages = 0;
+        $failures = 0;
+
+        foreach (glob($source . '/*', GLOB_ONLYDIR) ?: [] as $scenarioDirectory) {
+            $scenario = basename($scenarioDirectory);
+            $files = glob($scenarioDirectory . '/*.xml') ?: [];
+            sort($files);
+
+            if (!is_dir($target . '/' . $scenario)) {
+                mkdir($target . '/' . $scenario, 0777, true);
+            }
+
+            $normalizer = new SamlXmlNormalizer();
+            $scenarios++;
+
+            foreach ($files as $file) {
+                try {
+                    $dump = $normalizer->normalize((string) file_get_contents($file));
+                } catch (InvalidArgumentException $exception) {
+                    $dump = '!! ' . $exception->getMessage() . "\n";
+                    $failures++;
+                }
+
+                file_put_contents($target . '/' . $scenario . '/' . basename($file, '.xml') . '.txt', $dump);
+                $messages++;
+            }
+        }
+
+        $output->writeln(sprintf(
+            'Normalized %d messages from %d scenarios (%d unparsable)',
+            $messages,
+            $scenarios,
+            $failures
+        ));
+
+        return Command::SUCCESS;
+    }
+}

src/OpenConext/EngineBlockFunctionalTestingBundle/Features/Context/SamlRecordingContext.php

@@ -0,0 +1,71 @@
+<?php
+
+/**
+ * Copyright 2026 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.
+ */
+
+declare(strict_types=1);
+
+namespace OpenConext\EngineBlockFunctionalTestingBundle\Features\Context;
+
+use Behat\Behat\Context\Context;
+use Behat\Behat\Hook\Scope\BeforeScenarioScope;
+use OpenConext\EngineBlockFunctionalTestingBundle\Saml2\Recording\SamlTrafficRecorder;
+
+class SamlRecordingContext implements Context
+{
+    // The application runs in Apache, so the recorder is told what to do through a marker file, not an env var.
+    /**
+     * @BeforeScenario
+     */
+    public function markCurrentScenario(BeforeScenarioScope $scope): void
+    {
+        $directory = getenv(SamlTrafficRecorder::DIRECTORY_ENV);
+        if (!is_string($directory) || $directory === '') {
+            self::clearMarker();
+            return;
+        }
+
+        if (!is_dir($directory)) {
+            mkdir($directory, 0777, true);
+        }
+
+        $scenario = sprintf(
+            '%s_L%d',
+            basename($scope->getFeature()->getFile() ?? 'unknown', '.feature'),
+            $scope->getScenario()->getLine()
+        );
+
+        file_put_contents(
+            SamlTrafficRecorder::MARKER_FILE,
+            json_encode(['directory' => $directory, 'scenario' => $scenario], JSON_THROW_ON_ERROR)
+        );
+    }
+
+    /**
+     * @AfterSuite
+     */
+    public static function stopRecording(): void
+    {
+        self::clearMarker();
+    }
+
+    private static function clearMarker(): void
+    {
+        if (is_file(SamlTrafficRecorder::MARKER_FILE)) {
+            unlink(SamlTrafficRecorder::MARKER_FILE);
+        }
+    }
+}

src/OpenConext/EngineBlockFunctionalTestingBundle/Saml2/Recording/SamlTrafficRecorder.php

@@ -0,0 +1,199 @@
+<?php
+
+/**
+ * Copyright 2026 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.
+ */
+
+declare(strict_types=1);
+
+namespace OpenConext\EngineBlockFunctionalTestingBundle\Saml2\Recording;
+
+use DOMDocument;
+use DOMXPath;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Event\ResponseEvent;
+use Symfony\Component\HttpKernel\KernelEvents;
+
+final class SamlTrafficRecorder implements EventSubscriberInterface
+{
+    public const DIRECTORY_ENV = 'EB_SAML_RECORD_DIR';
+    public const MARKER_FILE = '/tmp/eb-fixtures/saml-recording.json';
+
+    private const MESSAGE_PARAMETERS = ['SAMLRequest', 'SAMLResponse'];
+
+    public function __construct(private readonly string $markerFile = self::MARKER_FILE)
+    {
+    }
+
+    public static function getSubscribedEvents(): array
+    {
+        return [KernelEvents::RESPONSE => ['onKernelResponse', -1024]];
+    }
+
+    public function onKernelResponse(ResponseEvent $event): void
+    {
+        $recording = $this->readMarker();
+        if ($recording === null) {
+            return;
+        }
+
+        $messages = $this->extractMessages($event->getResponse());
+        if ($messages === []) {
+            return;
+        }
+
+        $request = $event->getRequest();
+        $source = preg_replace('/[^A-Za-z0-9.]+/', '_', $request->getHost() . $request->getPathInfo());
+
+        foreach ($messages as $type => $xml) {
+            $this->write($recording['directory'], $recording['scenario'], $type, (string) $source, $xml);
+        }
+    }
+
+    /**
+     * @return array<string, string> SAML message type (SAMLRequest|SAMLResponse) => raw XML
+     */
+    public function extractMessages(Response $response): array
+    {
+        return $this->extractFromRedirect($response) + $this->extractFromForm($response);
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function extractFromRedirect(Response $response): array
+    {
+        $location = $response->headers->get('Location');
+        if ($location === null) {
+            return [];
+        }
+
+        parse_str((string) parse_url($location, PHP_URL_QUERY), $query);
+
+        $messages = [];
+        foreach (self::MESSAGE_PARAMETERS as $parameter) {
+            $xml = is_string($query[$parameter] ?? null) ? $this->decode($query[$parameter], true) : null;
+            if ($xml !== null) {
+                $messages[$parameter] = $xml;
+            }
+        }
+
+        return $messages;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function extractFromForm(Response $response): array
+    {
+        $content = (string) $response->getContent();
+        if (!str_contains($content, 'SAML') || !str_contains((string) $response->headers->get('Content-Type'), 'html')) {
+            return [];
+        }
+
+        $messages = [];
+        foreach ($this->extractFormFields($content) as $parameter => $value) {
+            $xml = $this->decode($value, false);
+            if ($xml !== null) {
+                $messages[$parameter] = $xml;
+            }
+        }
+
+        return $messages;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function extractFormFields(string $html): array
+    {
+        $previous = libxml_use_internal_errors(true);
+        $document = new DOMDocument();
+        $document->loadHTML($html);
+        libxml_clear_errors();
+        libxml_use_internal_errors($previous);
+
+        $fields = [];
+        $xpath = new DOMXPath($document);
+        foreach ($xpath->query('//input[@name="SAMLRequest" or @name="SAMLResponse"]') as $input) {
+            $fields[$input->getAttribute('name')] = $input->getAttribute('value');
+        }
+
+        return $fields;
+    }
+
+    private function decode(string $encoded, bool $deflated): ?string
+    {
+        $decoded = base64_decode($encoded, true);
+        if ($decoded === false) {
+            return null;
+        }
+
+        if ($deflated) {
+            $decoded = $this->inflate($decoded) ?? $decoded;
+        }
+
+        return str_starts_with(ltrim($decoded), '<') ? $decoded : null;
+    }
+
+    private function inflate(string $data): ?string
+    {
+        // Recording must never break the request, so a corrupt payload is ignored instead of raising a warning.
+        set_error_handler(static fn(): bool => true);
+        try {
+            $inflated = gzinflate($data);
+        } finally {
+            restore_error_handler();
+        }
+
+        return $inflated === false ? null : $inflated;
+    }
+
+    /**
+     * @return array{directory: string, scenario: string}|null
+     */
+    private function readMarker(): ?array
+    {
+        if (!is_file($this->markerFile)) {
+            return null;
+        }
+
+        $marker = json_decode((string) file_get_contents($this->markerFile), true);
+        if (!is_array($marker) || !is_string($marker['directory'] ?? null) || $marker['directory'] === '') {
+            return null;
+        }
+
+        return [
+            'directory' => $marker['directory'],
+            'scenario' => is_string($marker['scenario'] ?? null) && $marker['scenario'] !== ''
+                ? $marker['scenario']
+                : 'unscoped',
+        ];
+    }
+
+    private function write(string $directory, string $scenario, string $type, string $source, string $xml): void
+    {
+        $scenarioDirectory = $directory . '/' . $scenario;
+
+        if (!is_dir($scenarioDirectory)) {
+            mkdir($scenarioDirectory, 0777, true);
+        }
+
+        $sequence = count(glob($scenarioDirectory . '/*.xml') ?: []) + 1;
+
+        file_put_contents(sprintf('%s/%03d-%s-%s.xml', $scenarioDirectory, $sequence, $type, $source), $xml);
+    }
+}