[Saml2] Allow the administrator to choose an entity descriptor to use (#984)

Co-authored-by: atymic <atymicq@gmail.com>

Author: 27pchrisl

Provider.php

@@ -267,20 +267,33 @@ protected function getIdentityProviderEntityDescriptorManually(): EntityDescript
         return $builder->get();
     }
 
-    protected function getFirstEntityDescriptorFromXml(string $xml): EntityDescriptor
+    protected function getIdpEntityDescriptorFromXml(string $xml): EntityDescriptor
     {
-        $descriptor = Metadata::fromXML($xml, new DeserializationContext());
+        /** @var EntitiesDescriptor|EntityDescriptor $metadata */
+        $metadata = Metadata::fromXML($xml, new DeserializationContext());
 
-        if ($descriptor instanceof EntitiesDescriptor) {
-            return Arr::first($descriptor->getAllEntityDescriptors());
+        if ($metadata instanceof EntityDescriptor) {
+            return $metadata;
         }
 
-        return $descriptor;
+        $entityId = $this->getConfig('entityid');
+
+        if (!$entityId) {
+            return Arr::first($metadata->getAllEntityDescriptors());
+        }
+
+        $entityDescriptor = $metadata->getByEntityId($entityId);
+
+        if (null === $entityDescriptor) {
+            throw new MissingConfigException(sprintf('The IDP descriptor with entity id %s could not be found in the metadata.', $entityId));
+        }
+
+        return $entityDescriptor;
     }
 
     protected function getIdentityProviderEntityDescriptorFromXml(): EntityDescriptor
     {
-        return $this->getFirstEntityDescriptorFromXml($this->getConfig('metadata'));
+        return $this->getIdpEntityDescriptorFromXml($this->getConfig('metadata'));
     }
 
     protected function getIdentityProviderEntityDescriptorFromUrl(): EntityDescriptor
@@ -290,7 +303,7 @@ protected function getIdentityProviderEntityDescriptorFromUrl(): EntityDescripto
         $ttl = Cache::get(self::METADATA_CACHE_KEY_TTL);
 
         if ($xml && $ttl && $ttl + $this->getConfig('ttl', 86400) > time()) {
-            return $this->getFirstEntityDescriptorFromXml($xml);
+            return $this->getIdpEntityDescriptorFromXml($xml);
         }
 
         Cache::forever(self::METADATA_CACHE_KEY_TTL, time());
@@ -307,7 +320,7 @@ protected function getIdentityProviderEntityDescriptorFromUrl(): EntityDescripto
             }
         }
 
-        return $this->getFirstEntityDescriptorFromXml($xml);
+        return $this->getIdpEntityDescriptorFromXml($xml);
     }
 
     /**

README.md

@@ -29,6 +29,18 @@ Using a metadata URL is highly recommended if your IDP supports it, so that cert
 ],
 ```
 
+The provider will automatically choose the first IdP descriptor in your metadata.
+If your metadata contains multiple descriptors, you can choose the one to use by using both the `metadata` and `entityid`
+configuration options at the same time.
+
+#### Using an Identity Provider metadata URL, selecting a specific descriptor
+```php
+'saml2' => [
+  'metadata' => 'https://idp.co/metadata/xml',
+  'entityid' => 'http://saml.to/trust',
+],
+```
+
 #### Manually configuring the Identity Provider with a certificate string:
 ```php
 'saml2' => [

composer.json

@@ -23,7 +23,7 @@
     "require": {
         "php": "^7.4 || ^8.0",
         "ext-json": "*",
-        "litesaml/lightsaml": "^3.0",
+        "litesaml/lightsaml": "^4.0",
         "socialiteproviders/manager": "~4.0"
     },
     "autoload": {