Add support for preferred IdPs in WAYF display

Prior to this change, there was no way to configure priority IdPs.

This change adds a `wayf.preferred_idp_entity_ids` parameter to configure IdPs that should show prominent in the wayf.
IdPs in this list are shown on top of the wayf, outside of the regular list.

Resolves #1970

Author: johanib

CHANGELOG.md

@@ -29,7 +29,10 @@ Changes:
   * The `0000-00-00 00:00:00` is added for clarity/consistency, as this is probably the default behaviour of your database already.
 * Removed unused index `consent.deleted_at`. Delete this from your production database if it's there.
 * Added a specific error page for unsolicited SAML responses (IdP-initiated SSO without a prior AuthnRequest).
+* A new parameter `wayf.preferred_idp_entity_ids` must be added to `parameters.yml`. To display a set of IdPs prominent at the top of the WAYF, add the entityId's of those IdPs to this parameter.
+  * To keep the old behaviour, set the value to `[]`
 
+**Default behaviour (no change):** when the parameter is absent or empty, the WAYF behaves exactly as before.
 * Stabilized consent checks
   * In order to make the consent hashes more robust, a more consistent way of hashing the user attributes has been introduced
   * This feature automatically migrates from the old hashes to the new hashes upon login.

config/packages/parameters.yml.dist

@@ -187,6 +187,11 @@ parameters:
     wayf.display_default_idp_banner_on_wayf: true
     wayf.default_idp_entity_id: https://default-idp.dev.openconext.local
 
+    ## Ordered list of IdP entity IDs to feature prominently at the top of the WAYF.
+    ## These IdPs appear above the search field and are excluded from the regular searchable list.
+    ## An empty list means no behaviour change.
+    wayf.preferred_idp_entity_ids: []
+
     ## Toggle display & content of global site notice
     global.site_notice.show: false
     global.site_notice.allowed.tags: '<a><u><i><br><wbr><strong><em><blink><marquee><p><ul><ol><dl><li><dd><dt><div><span><blockquote><hr><h2></h2><h3><h4><h5><h6>'

config/services/services.yml

@@ -2,9 +2,17 @@ services:
     _defaults:
         public: true
 
+    OpenConext\EngineBlock\Service\Wayf\IdpSplitter:
+
+    OpenConext\EngineBlockBundle\Service\WayfViewModelFactory:
+        arguments:
+            $wayfExtension: '@OpenConext\EngineBlockBundle\Twig\Extensions\Extension\Wayf'
+
     OpenConext\EngineBlockBundle\Bridge\EngineBlockBootstrapper:
         autowire: true
         autoconfigure: true
+        arguments:
+            $preferredIdpEntityIds: '%wayf.preferred_idp_entity_ids%'
         tags:
             - { name: kernel.event_subscriber }
 

docs/testing.md

@@ -0,0 +1,52 @@
+# Testing
+
+## WAYF functional-testing page
+
+The functional-testing route renders the WAYF page with synthetic IdP data, controllable via query parameters. Use it for manual verification and as the base URL for Cypress tests.
+
+**Base URL:** `https://engine.dev.openconext.local/functional-testing/wayf`
+
+### Query parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `lang` | string | `en` | Locale (`en` or `nl`) |
+| `connectedIdps` | int | `5` | Number of connected IdPs to generate |
+| `unconnectedIdps` | int | `0` | Number of unconnected IdPs to generate |
+| `randomIdps` | int | `0` | Generate N IdPs with random (Faker) names instead; overrides connected/unconnected |
+| `addDiscoveries` | bool | `true` | Add discovery entries to IdP 1 (gives it 3 list entries instead of 1) |
+| `preferredIdpEntityIds[]` | string[] | `[]` | Entity IDs to feature in the preferred section (array syntax required) |
+| `defaultIdpEntityId` | string | - | Entity ID of the default IdP (shows banner) |
+| `showIdPBanner` | bool | `true` | Whether to show the default IdP banner |
+| `displayUnconnectedIdpsWayf` | bool | `false` | Show unconnected IdPs with a "Request access" button |
+| `backLink` | bool | `false` | Show "Return to service provider" back link |
+| `rememberChoiceFeature` | bool | `false` | Show "Remember my choice" checkbox |
+| `cutoffPointForShowingUnfilteredIdps` | int | `100` | Hide the IdP list until the user searches when list length exceeds this value |
+
+#### Baseline
+- [Default (5 connected IdPs)](https://engine.dev.openconext.local/functional-testing/wayf)
+- [Dutch locale](https://engine.dev.openconext.local/functional-testing/wayf?lang=nl)
+- [10 IdPs](https://engine.dev.openconext.local/functional-testing/wayf?connectedIdps=10&addDiscoveries=false)
+- [Random IdPs (Faker names)](https://engine.dev.openconext.local/functional-testing/wayf?randomIdps=8)
+
+#### Cutoff / search
+- [Cutoff active - list hidden until search](https://engine.dev.openconext.local/functional-testing/wayf?connectedIdps=6&cutoffPointForShowingUnfilteredIdps=5)
+
+#### Unconnected IdPs / request access
+- [Unconnected IdPs visible, no request access](https://engine.dev.openconext.local/functional-testing/wayf?unconnectedIdps=3)
+- [Unconnected IdPs + request access button](https://engine.dev.openconext.local/functional-testing/wayf?unconnectedIdps=3&displayUnconnectedIdpsWayf=true)
+
+#### UI features
+- [Back link](https://engine.dev.openconext.local/functional-testing/wayf?backLink=true)
+- [Remember my choice](https://engine.dev.openconext.local/functional-testing/wayf?rememberChoiceFeature=true)
+- [Default IdP banner](https://engine.dev.openconext.local/functional-testing/wayf?defaultIdpEntityId=https%3A%2F%2Fexample.com%2FentityId%2F3&showIdPBanner=true&addDiscoveries=false)
+
+#### Preferred IdPs
+- [1 preferred IdP](https://engine.dev.openconext.local/functional-testing/wayf?preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1&addDiscoveries=false)
+- [2 preferred IdPs](https://engine.dev.openconext.local/functional-testing/wayf?preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1&preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F2&addDiscoveries=false)
+- [Preferred = default IdP > banner suppressed](https://engine.dev.openconext.local/functional-testing/wayf?preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1&defaultIdpEntityId=https%3A%2F%2Fexample.com%2FentityId%2F1&showIdPBanner=true&addDiscoveries=false)
+- [Preferred ≠ default IdP > both visible](https://engine.dev.openconext.local/functional-testing/wayf?preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1&defaultIdpEntityId=https%3A%2F%2Fexample.com%2FentityId%2F2&showIdPBanner=true&addDiscoveries=false)
+- [Preferred IdP with discoveries (1 IdP > 3 entries)](https://engine.dev.openconext.local/functional-testing/wayf?preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1)
+
+
+- [All features enabled](https://engine.dev.openconext.local/functional-testing/wayf?connectedIdps=8&unconnectedIdps=2&displayUnconnectedIdpsWayf=true&preferredIdpEntityIds%5B%5D=https%3A%2F%2Fexample.com%2FentityId%2F1&defaultIdpEntityId=https%3A%2F%2Fexample.com%2FentityId%2F2&showIdPBanner=true&backLink=true&rememberChoiceFeature=true&addDiscoveries=false)

library/EngineBlock/Corto/Module/Service/SingleSignOn.php

@@ -462,8 +462,6 @@ protected function _showWayf(EngineBlock_Saml2_AuthnRequestAnnotationDecorator $
 
         $currentLocale = $container->getLocaleProvider()->getLocale();
 
-        $cookies = $container->getSymfonyRequest()->cookies->all();
-
         if ($request->isDebugRequest()) {
             $serviceProvider = $this->getEngineSpRole($this->_server);
         } else {
@@ -478,27 +476,39 @@ protected function _showWayf(EngineBlock_Saml2_AuthnRequestAnnotationDecorator $
         );
 
         $defaultIdPInIdPList = $this->isDefaultIdPPresent($idpList);
-        $showDefaultIdpBanner = (bool) $container->shouldDisplayDefaultIdpBannerOnWayf() && $defaultIdPInIdPList;
+
+        $diContainerRuntime = $application->getDiContainerRuntime();
+        $preferredIdpEntityIds = $diContainerRuntime->getPreferredIdpEntityIds();
+        $split = $diContainerRuntime->idpSplitter->split($idpList, $preferredIdpEntityIds);
+        $showPreferredIdps = !empty($split['preferred']);
+        $isDefaultIdpPreferred = in_array($container->getDefaultIdPEntityId(), $preferredIdpEntityIds, true);
+        $showDefaultIdpBanner = (bool) $container->shouldDisplayDefaultIdpBannerOnWayf()
+            && $defaultIdPInIdPList
+            && (!$showPreferredIdps || !$isDefaultIdpPreferred);
 
         $rememberChoiceFeature = $container->getRememberChoice();
 
+        $viewModel = $diContainerRuntime->wayfViewModelFactory->create(
+            idpList: $idpList,
+            regularIdpList: $split['regular'],
+            preferredIdpList: $split['preferred'],
+            showPreferredIdps: $showPreferredIdps,
+            action: $action,
+            greenHeader: $serviceProvider->getDisplayName($currentLocale),
+            helpLink: '/authentication/idp/help-discover?lang=' . $currentLocale,
+            backLink: $container->isUiOptionReturnToSpActive(),
+            cutoffPointForShowingUnfilteredIdps: $container->getCutoffPointForShowingUnfilteredIdps(),
+            showIdPBanner: $showDefaultIdpBanner,
+            rememberChoiceFeature: $rememberChoiceFeature,
+            showRequestAccess: $serviceProvider->getCoins()->displayUnconnectedIdpsWayf(),
+            requestId: $request->getId(),
+            serviceProvider: $serviceProvider,
+            showRequestAccessContainer: true,
+        );
+
         $output = $this->twig->render(
             '@theme/Authentication/View/Proxy/wayf.html.twig',
-            [
-                'action' => $action,
-                'greenHeader' => $serviceProvider->getDisplayName($currentLocale),
-                'helpLink' => '/authentication/idp/help-discover?lang=' . $currentLocale,
-                'backLink' => $container->isUiOptionReturnToSpActive(),
-                'cutoffPointForShowingUnfilteredIdps' => $container->getCutoffPointForShowingUnfilteredIdps(),
-                'showIdPBanner' => $showDefaultIdpBanner,
-                'rememberChoiceFeature' => $rememberChoiceFeature,
-                'showRequestAccess' => $serviceProvider->getCoins()->displayUnconnectedIdpsWayf(),
-                'requestId' => $request->getId(),
-                'serviceProvider' => $serviceProvider,
-                'idpList' => $idpList,
-                'cookies' => $cookies,
-                'showRequestAccessContainer' => true,
-            ]
+            $viewModel->toArray()
         );
         $this->_server->sendOutput($output);
     }

src/OpenConext/EngineBlock/Service/Wayf/IdpSplitter.php

@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * Copyright 2025 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\Service\Wayf;
+
+final class IdpSplitter
+{
+    /**
+     * Splits the full IdP list into preferred (connected, in configured order) and regular (everything else).
+     * Preferred IdPs that are not connected are excluded from both sections.
+     *
+     * @param array  $idpList           Full transformed IdP list
+     * @param array  $preferredEntityIds Ordered list of entity IDs to feature at the top
+     * @return array{preferred: array, regular: array}
+     */
+    public function split(array $idpList, array $preferredEntityIds): array
+    {
+        if (empty($preferredEntityIds)) {
+            return ['preferred' => [], 'regular' => $idpList];
+        }
+
+        $orderMap = array_flip($preferredEntityIds);
+        $preferredBuckets = array_fill(0, count($preferredEntityIds), []);
+        $regular = [];
+
+        foreach ($idpList as $idp) {
+            $entityId = $idp['EntityID'];
+            if (isset($orderMap[$entityId])) {
+                if ($idp['Access'] === '1') {
+                    $preferredBuckets[$orderMap[$entityId]][] = $idp;
+                }
+                // Unconnected preferred IdPs are excluded from both sections.
+            } else {
+                $regular[] = $idp;
+            }
+        }
+
+        $mergeArgs = array_values(array_filter($preferredBuckets));
+        $preferred = empty($mergeArgs) ? [] : array_merge(...$mergeArgs);
+
+        return ['preferred' => $preferred, 'regular' => $regular];
+    }
+}

src/OpenConext/EngineBlockBundle/Bridge/DiContainerRuntime.php

@@ -18,6 +18,8 @@
 
 namespace OpenConext\EngineBlockBundle\Bridge;
 
+use OpenConext\EngineBlock\Service\Wayf\IdpSplitter;
+use OpenConext\EngineBlockBundle\Service\WayfViewModelFactory;
 use Twig\Environment;
 
 /**
@@ -29,7 +31,16 @@
 final readonly class DiContainerRuntime
 {
 
-    public function __construct(public Environment $twig)
+    public function __construct(
+        public Environment $twig,
+        public IdpSplitter $idpSplitter,
+        public WayfViewModelFactory $wayfViewModelFactory,
+        private array $preferredIdpEntityIds = [],
+    ) {
+    }
+
+    public function getPreferredIdpEntityIds(): array
     {
+        return $this->preferredIdpEntityIds;
     }
 }

src/OpenConext/EngineBlockBundle/Bridge/EngineBlockBootstrapper.php

@@ -19,6 +19,8 @@
 namespace OpenConext\EngineBlockBundle\Bridge;
 
 use EngineBlock_ApplicationSingleton;
+use OpenConext\EngineBlock\Service\Wayf\IdpSplitter;
+use OpenConext\EngineBlockBundle\Service\WayfViewModelFactory;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\HttpKernel\KernelEvents;
 use Twig\Environment;
@@ -29,8 +31,11 @@ class EngineBlockBootstrapper implements EventSubscriberInterface
 
     public function __construct(
         Environment $twig,
+        IdpSplitter $idpSplitter,
+        WayfViewModelFactory $wayfViewModelFactory,
+        array $preferredIdpEntityIds = [],
     ) {
-        $this->diContainerRuntime = new DiContainerRuntime($twig);
+        $this->diContainerRuntime = new DiContainerRuntime($twig, $idpSplitter, $wayfViewModelFactory, $preferredIdpEntityIds);
     }
 
     public function onKernelRequest(): void

src/OpenConext/EngineBlockBundle/Service/WayfViewModelFactory.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * Copyright 2025 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\EngineBlockBundle\Service;
+
+use OpenConext\EngineBlock\Metadata\Entity\ServiceProvider;
+use OpenConext\EngineBlockBundle\Twig\Extensions\Extension\Wayf;
+use OpenConext\EngineBlockBundle\ViewModel\WayfViewModel;
+
+class WayfViewModelFactory
+{
+    public function __construct(
+        private readonly Wayf $wayfExtension,
+    ) {
+    }
+
+    /**
+     * @SuppressWarnings(PHPMD.ExcessiveParameterList)
+     */
+    public function create(
+        array $idpList,
+        array $regularIdpList,
+        array $preferredIdpList,
+        bool $showPreferredIdps,
+        string $action,
+        string $greenHeader,
+        string $helpLink,
+        bool $backLink,
+        int $cutoffPointForShowingUnfilteredIdps,
+        bool $showIdPBanner,
+        bool $rememberChoiceFeature,
+        bool $showRequestAccess,
+        string $requestId,
+        ServiceProvider $serviceProvider,
+        bool $showRequestAccessContainer,
+    ): WayfViewModel {
+        return new WayfViewModel(
+            action: $action,
+            greenHeader: $greenHeader,
+            helpLink: $helpLink,
+            backLink: $backLink,
+            cutoffPointForShowingUnfilteredIdps: $cutoffPointForShowingUnfilteredIdps,
+            showIdPBanner: $showIdPBanner,
+            rememberChoiceFeature: $rememberChoiceFeature,
+            showRequestAccess: $showRequestAccess,
+            showRequestAccessContainer: $showRequestAccessContainer,
+            requestId: $requestId,
+            serviceProvider: $serviceProvider,
+            connectedIdps: $this->wayfExtension->getConnectedIdps($idpList),
+            regularConnectedIdps: $this->wayfExtension->getConnectedIdps($regularIdpList),
+            preferredConnectedIdps: $this->wayfExtension->getConnectedIdps($preferredIdpList),
+            showPreferredIdps: $showPreferredIdps,
+            idpList: $idpList,
+            regularIdpList: $regularIdpList,
+            preferredIdpList: $preferredIdpList,
+        );
+    }
+}

src/OpenConext/EngineBlockBundle/Twig/Extensions/Extension/Locale.php

@@ -75,13 +75,9 @@ public function getQueryStringFor($locale)
             $params
         );
 
-        $query = '';
-        foreach ($params as $key => $value) {
-            $query .= (strlen($query) == 0) ? '?' : '&' ;
-            $query .= $key. '=' .urlencode($value);
-        }
+        $query = http_build_query($params);
 
-        return $query;
+        return strlen($query) > 0 ? '?' . $query : '';
     }
 
     #[AsTwigFunction(name: 'locale')]