Backport support for IDP Discovery protocol (#2402)

tvdijen · thijskh · web-flow · commit 3fcc6903e9e8 · 2025-03-17T11:45:45.000+01:00
* Backport support for IDP Discovery protocol

* Add default DiscoveryResponse endpoints to generated SP metadata

---------

Co-authored-by: Thijs Kinkhorst &lt;thijs@kinkhorst.com&gt;
diff --git a/composer.json b/composer.json
@@ -64,7 +64,7 @@
         "simplesamlphp/assert": "^1.1",
         "simplesamlphp/composer-module-installer": "^1.3",
         "simplesamlphp/saml2": "^5@dev",
-        "simplesamlphp/saml2-legacy": "^4.17",
+        "simplesamlphp/saml2-legacy": "^4.18.1",
         "simplesamlphp/simplesamlphp-assets-base": "~2.3.0",
         "simplesamlphp/xml-security": "^1.7",
         "symfony/cache": "^6.4",
diff --git a/composer.lock b/composer.lock
diff --git a/docs/simplesamlphp-metadata-extensions-idpdisc.md b/docs/simplesamlphp-metadata-extensions-idpdisc.md
@@ -0,0 +1,47 @@
+SAML V2.0 Metadata Extensions for Identity Provider Discovery Service Protocol and Profile
+=============================
+
+[TOC]
+
+This is a reference for the SimpleSAMLphp implementation of the [SAML
+V2.0 Metadata Extensions for Identity Provider Discovery Service Protocol and Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf)
+defined by OASIS.
+
+The metadata extension is available to SP usage of SimpleSAMLphp. The entries are placed inside the relevant
+entry in `authsources.php`.
+
+An example:
+
+    <?php
+    $config = [
+
+        'default-sp' => [
+            'saml:SP',
+
+            'DiscoveryResponse' => [
+                [
+                    'index' => 1,
+                    'Binding' => 'urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol',
+                    'Location' => 'https://simplesamlphp.org/some/endpoint',
+                    'isDefault' => true,
+                ],
+            ],
+            /* ... */
+        ],
+    ];
+
+Generated XML Metadata Examples
+----------------
+
+The example given above will generate the following XML metadata:
+
+    <?xml version="1.0"?>
+    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://example.com/saml-idp">
+      <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+        <md:Extensions>
+          <idpdisc:DiscoveryResponse xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="https://simplesamlphp.org/some/endpoint" index="1" isDefault="true" />
+        </md:Extensions>
+        <md:KeyDescriptor use="signing">
+          <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+            <ds:X509Data>
+            ...
diff --git a/modules/saml/docs/sp.md b/modules/saml/docs/sp.md
@@ -12,6 +12,7 @@ and with entity attributes. See the documentation for those extensions for more
 * [MDUI extension](../simplesamlphp-metadata-extensions-ui)
 * [MDRPI extension](../simplesamlphp-metadata-extensions-rpi)
 * [Attributes extension](../simplesamlphp-metadata-extensions-attributes)
+* [DiscoveryResponse extension](../simplesamlphp-metadata-extensions-idpdisc)
 
 **Parameters**:
 
diff --git a/modules/saml/src/Auth/Source/SP.php b/modules/saml/src/Auth/Source/SP.php
@@ -164,6 +164,7 @@ public function getHostedMetadata(): array
             'metadata-set' => 'saml20-sp-remote',
             'SingleLogoutService' => $this->getSLOEndpoints(),
             'AssertionConsumerService' => $this->getACSEndpoints(),
+            'DiscoveryResponse' => $this->getDiscoveryResponseEndpoints(),
         ];
 
         // add NameIDPolicy
@@ -441,6 +442,19 @@ private function getSLOEndpoints(): array
         return $endpoints;
     }
 
+    /**
+     * Get the DiscoveryResponse endpoint available for a given local SP.
+     */
+    private function getDiscoveryResponseEndpoints(): array
+    {
+        $location = Module::getModuleURL('saml/sp/discoResponse/' . $this->getAuthId());
+
+        return [ 0 => [
+                'Binding' => Constants::NS_IDPDISC,
+                'Location' => $location,
+        ] ];
+    }
+
     /**
      * Determine if the Request Initiator Protocol is enabled
      *
diff --git a/modules/saml/src/IdP/SAML2.php b/modules/saml/src/IdP/SAML2.php
@@ -949,7 +949,6 @@ public static function getHostedMetadata(string $entityid, MetaDataStorageHandle
             $metadata['saml:Extensions'] = $config->getArray('saml:Extensions');
         }
 
-
         if ($config->hasValue('UIInfo')) {
             $metadata['UIInfo'] = $config->getArray('UIInfo');
         }
diff --git a/src/SimpleSAML/Metadata/SAMLBuilder.php b/src/SimpleSAML/Metadata/SAMLBuilder.php
@@ -6,6 +6,7 @@
 
 use DOMElement;
 use SAML2\Constants;
+use SAML2\XML\idpdisc\DiscoveryResponse;
 use SAML2\XML\md\AttributeAuthorityDescriptor;
 use SAML2\XML\md\AttributeConsumingService;
 use SAML2\XML\md\ContactPerson;
@@ -202,6 +203,14 @@ private function addExtensions(Configuration $metadata, RoleDescriptor $e): void
             );
         }
 
+        if ($metadata->hasValue('DiscoveryResponse')) {
+            $discoResponse = self::createEndpoints($metadata->getArray('DiscoveryResponse'), true);
+
+            $e->setExtensions(
+                array_merge($e->getExtensions(), $discoResponse),
+            );
+        }
+
         if ($metadata->hasValue('UIInfo')) {
             $ui = new UIInfo();
             foreach ($metadata->getArray('UIInfo') as $uiName => $uiValues) {
@@ -323,7 +332,12 @@ private static function createEndpoints(array $endpoints, bool $indexed): array
 
         foreach ($endpoints as &$ep) {
             if ($indexed) {
-                $t = new IndexedEndpointType();
+                if ($ep['Binding'] === Constants::NS_IDPDISC) {
+                    $t = new DiscoveryResponse();
+                } else {
+                    $t = new IndexedEndpointType();
+                }
+
                 if (!isset($ep['index'])) {
                     // Find the maximum index
                     $maxIndex = -1;
diff --git a/src/SimpleSAML/Metadata/SAMLParser.php b/src/SimpleSAML/Metadata/SAMLParser.php
@@ -13,6 +13,7 @@
 use SAML2\SignedElementHelper;
 use SAML2\XML\ds\X509Certificate;
 use SAML2\XML\ds\X509Data;
+use SAML2\XML\idpdisc\DiscoveryResponse;
 use SAML2\XML\md\AttributeAuthorityDescriptor;
 use SAML2\XML\md\AttributeConsumingService;
 use SAML2\XML\md\ContactPerson;
@@ -507,6 +508,10 @@ private function addExtensions(array &$metadata, array $roleDescriptor): void
             }
         }
 
+        if (!empty($roleDescriptor['DiscoveryResponse'])) {
+            $metadata['DiscoveryResponse'] = $roleDescriptor['DiscoveryResponse'];
+        }
+
         if (!empty($roleDescriptor['UIInfo'])) {
             $metadata['UIInfo'] = $roleDescriptor['UIInfo'];
         }
@@ -737,6 +742,7 @@ private static function parseRoleDescriptorType(RoleDescriptor $element, ?int $e
         $ext = self::processExtensions($element);
         $ret['scope'] = $ext['scope'];
         $ret['EntityAttributes'] = $ext['EntityAttributes'];
+        $ret['DiscoveryResponse'] = $ext['DiscoveryResponse'];
         $ret['UIInfo'] = $ext['UIInfo'];
         $ret['DiscoHints'] = $ext['DiscoHints'];
 
@@ -770,7 +776,6 @@ private static function parseSSODescriptor(SSODescriptorType $element, ?int $exp
         // find all ArtifactResolutionService elements
         $sd['ArtifactResolutionService'] = self::extractEndpoints($element->getArtifactResolutionService());
 
-
         // process NameIDFormat elements
         $sd['nameIDFormats'] = $element->getNameIDFormat();
 
@@ -873,11 +878,12 @@ private function processAttributeAuthorityDescriptor(
     private static function processExtensions(mixed $element, array $parentExtensions = []): array
     {
         $ret = [
-            'scope'            => [],
-            'EntityAttributes' => [],
-            'RegistrationInfo' => [],
-            'UIInfo'           => [],
-            'DiscoHints'       => [],
+            'scope'             => [],
+            'EntityAttributes'  => [],
+            'RegistrationInfo'  => [],
+            'DiscoveryResponse' => [],
+            'UIInfo'            => [],
+            'DiscoHints'        => [],
         ];
 
         // Some extensions may get inherited from a parent element
@@ -955,6 +961,13 @@ private static function processExtensions(mixed $element, array $parentExtension
                 }
             }
 
+            // DiscoveryResponse elements only make sense at SPSSODescriptor level extensions
+            if ($element instanceof SPSSODescriptor) {
+                if ($e instanceof DiscoveryResponse) {
+                    $ret['DiscoveryResponse'] = array_merge($ret['DiscoveryResponse'], self::extractEndpoints([$e]));
+                }
+            }
+
             // UIInfo elements are only allowed at RoleDescriptor level extensions
             if ($element instanceof RoleDescriptor) {
                 if ($e instanceof UIInfo) {
diff --git a/tests/src/SimpleSAML/Metadata/SAMLParserTest.php b/tests/src/SimpleSAML/Metadata/SAMLParserTest.php
@@ -6,6 +6,7 @@
 
 use DOMDocument;
 use PHPUnit\Framework\Attributes\CoversClass;
+use SAML2\Constants;
 use SAML2\DOMDocumentFactory;
 use SimpleSAML\Metadata\SAMLParser;
 use SimpleSAML\Test\SigningTestCase;
@@ -17,6 +18,41 @@
 #[CoversClass(SAMLParser::class)]
 class SAMLParserTest extends SigningTestCase
 {
+    /**
+     * Test that DiscoveryResponse is parsed
+     */
+    public function testDiscoveryResponse(): void
+    {
+        $expected = [
+            0 => [
+                'index' => 43,
+                'Binding' => Constants::NS_IDPDISC,
+                'Location' => 'https://simplesamlphp.org/some/endpoint',
+                'isDefault' => false,
+            ],
+        ];
+
+        $document = DOMDocumentFactory::fromString(
+            <<<XML
+<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="theEntityID">
+  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+    <Extensions>
+      <idpdisc:DiscoveryResponse xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="https://simplesamlphp.org/some/endpoint" index="43" isDefault="false" />
+    </Extensions>
+  </SPSSODescriptor>
+</EntityDescriptor>
+XML,
+        );
+
+        $entities = SAMLParser::parseDescriptorsElement($document->documentElement);
+        $this->assertArrayHasKey('theEntityID', $entities);
+        // DiscoveryResponse is accessible in the SP metadata accessors
+        /** @var array $metadata */
+        $metadata = $entities['theEntityID']->getMetadata20SP();
+        $this->assertEquals($expected, $metadata['DiscoveryResponse']);
+    }
+
+
     /**
      * Test Registration Info is parsed
      */

Original file line number	Diff line number	Diff line change
`@@ -949,7 +949,6 @@ public static function getHostedMetadata(string $entityid, MetaDataStorageHandle`
`949`	`949`	`$metadata['saml:Extensions'] = $config->getArray('saml:Extensions');`
`950`	`950`	`}`
`951`	`951`
`952`		`-`
`953`	`952`	`if ($config->hasValue('UIInfo')) {`
`954`	`953`	`$metadata['UIInfo'] = $config->getArray('UIInfo');`
`955`	`954`	`}`