feat: 🎸 Additional identifiers lookup

Author: Dominik Frantisek Bucik

config-templates/processFilterConfigurations-example.md

@@ -12,6 +12,8 @@ Example how to configure PerunIdentity module:
                 'registerUrlBase' => 'https://perun.cesnet.cz/allfed/registrar',
                 'registerUrl' => 'https://login.cesnet.cz/register',
                 'interface' => 'ldap',
+                'useAdditionalIdentifiersLookup' => true,
+                'additionalIdentifiersAttribute' => 'additionalIdentifiers',
                 'facilityCheckGroupMembershipAttr' => 'urn:perun:facility:attribute-def:def:checkGroupMembership',
                 'facilityVoShortNamesAttr' => 'urn:perun:facility:attribute-def:virt:voShortNames',
                 'facilityDynamicRegistrationAttr' => 'urn:perun:facility:attribute-def:def:dynamicRegistration',
@@ -193,6 +195,8 @@ Configuration options:
 * `register_url`: URL to which the user will be forwarded for registration. Leave empty to use the Perun registrar.
 * `callback_parameter_name`: name of the parameter wich will hold callback URL, where the user should be redirected after the registration on URL configured in the `register_url` property.
 * `perun_register_url`: the complete URL (including vo and group) to which user will be redirected, if `register_url` has not been configured. Parameters targetnew, targetexisting and targetextended will be set to callback URL to continue after the registration is completed.
+* `use_additional_identifiers_lookup`: `true` or `false`, set it to `true` if you want to use additionalIdentifiers as fallback lookup method if the standard one fails.
+* `additional_identifiers_attribute`: name of the attribute (from `$request['Attributes']` array), which holds the additional identifiers. If you use RPC adapter, the value in the attribute resolved using `idp_id_attr` will be used as well for locating the user in Perun. 
 
 ```php
 2 => [
@@ -202,7 +206,9 @@ Configuration options:
     'idp_id_attr' => 'authenticating_idp',
     'register_url' => 'https://signup.cesnet.cz/',
     'callback_parameter_name' => 'callback',
-    'perun_register_url' => 'https://signup.perun.cesnet.cz/fed/registrar/?vo=cesnet'
+    'perun_register_url' => 'https://signup.perun.cesnet.cz/fed/registrar/?vo=cesnet',
+    'use_additional_identifiers_lookup' => true,
+    'additional_identifiers_attribute' => 'additionalIdentifiers',
 ],
 ```
 

lib/Adapter.php

@@ -54,6 +54,14 @@ public static function getInstance($interface)
      */
     abstract public function getPerunUser($idpEntityId, $uids);
 
+    /**
+     * @param string $idpEntityId entity id of hosted idp used as extSourceName
+     * @param array  $uids        list of user identifiers received from remote idp used as userExtSourceLogin
+     *
+     * @return User or null if not exists
+     */
+    abstract public function getPerunUserByAdditionalIdentifiers($idpEntityId, $uids);
+
     /**
      * @param model\Vo $vo
      * @param string   $name group name. Note that name of group is without VO name prefix.

lib/AdapterLdap.php

@@ -100,19 +100,29 @@ public function getPerunUser($idpEntityId, $uids)
             '(|' . $query . ')',
             ['perunUserId', 'displayName', 'cn', 'givenName', 'sn', 'preferredMail', 'mail']
         );
-        if (null === $user) {
-            return $user;
+
+        return self::mapUser($user);
+    }
+
+    public function getPerunUserByAdditionalIdentifiers($idpEntityId, $uids)
+    {
+        // Build a LDAP query, we are searching for the user who has at least one of the uid
+        $query = '';
+        foreach ($uids as $uid) {
+            $query .= '(internalUserIdentifiers=' . $uid . ')';
         }
 
-        if (isset($user['displayName'][0])) {
-            $name = $user['displayName'][0];
-        } elseif (isset($user['cn'][0])) {
-            $name = $user['cn'][0];
-        } else {
-            $name = null;
+        if (empty($query)) {
+            return null;
         }
 
-        return new User($user['perunUserId'][0], $name);
+        $user = $this->connector->searchForEntity(
+            'ou=People,' . $this->ldapBase,
+            '(|' . $query . ')',
+            ['perunUserId', 'displayName', 'cn', 'givenName', 'sn', 'preferredMail', 'mail']
+        );
+
+        return self::mapUser($user);
     }
 
     public function getMemberGroups($user, $vo)
@@ -608,6 +618,22 @@ public function getFacilityCapabilities($entityId)
         return $facilityCapabilities['capabilities'];
     }
 
+    private function mapUser($user)
+    {
+        if (null === $user) {
+            return null;
+        }
+        if (isset($user['displayName'][0])) {
+            $name = $user['displayName'][0];
+        } elseif (isset($user['cn'][0])) {
+            $name = $user['cn'][0];
+        } else {
+            $name = null;
+        }
+
+        return new User($user['perunUserId'][0], $name);
+    }
+
     private function resolveAttrValue($attrsNameTypeMap, $attrsFromLdap, $attr)
     {
         if (!array_key_exists($attr, $attrsFromLdap)) {

lib/AdapterRpc.php

@@ -112,6 +112,11 @@ public function getPerunUser($idpEntityId, $uids)
         return $user;
     }
 
+    public function getPerunUserByAdditionalIdentifiers($idpEntityId, $uids)
+    {
+        return $this->getPerunUser($idpEntityId, $uids);
+    }
+
     public function getMemberGroups($user, $vo)
     {
         try {

lib/Auth/Process/PerunIdentity.php

@@ -16,6 +16,7 @@
 use SimpleSAML\Module\perun\model\Member;
 use SimpleSAML\Module\perun\model\User;
 use SimpleSAML\Module\perun\model\Vo;
+use SimpleSAML\Module\perun\PerunConstants;
 use SimpleSAML\Utils\HTTP;
 
 /**
@@ -66,6 +67,10 @@ class PerunIdentity extends \SimpleSAML\Auth\ProcessingFilter
 
     public const LIST_OF_SPS_WITHOUT_INFO_ABOUT_REDIRECTION = 'listOfSpsWithoutInfoAboutRedirection';
 
+    public const USE_ADDITIONAL_IDENTIFIERS_LOOKUP = 'useAdditionalIdentifiersLookup';
+
+    public const ADDITIONAL_IDENTIFIERS_ATTRIBUTE = 'additionalIdentifiersAttribute';
+
     public const MODE = 'mode';
 
     public const MODE_FULL = 'FULL';
@@ -188,6 +193,14 @@ public function __construct($config, $reserved)
             );
         }
 
+        $this->useAdditionalIdentifiersLookup = $config->getBoolean(self::USE_ADDITIONAL_IDENTIFIERS_LOOKUP, false);
+        $this->additionalIdentifiersAttribute = $config->getString(self::ADDITIONAL_IDENTIFIERS_ATTRIBUTE, null);
+        if ($this->useAdditionalIdentifiersLookup && null === $this->additionalIdentifiersAttribute) {
+            throw new Exception(
+                'perun:PerunIdentity: Invalid configuration: no attribute configured for extracting additional identifiers. Use option \'' . self::ADDITIONAL_IDENTIFIERS_ATTRIBUTE . '\' to configure the name of the attribute, that should be considered as additional identifiers of the user.'
+            );
+        }
+
         $this->adapter = Adapter::getInstance($this->interface);
         $this->rpcAdapter = new AdapterRpc();
     }
@@ -235,6 +248,15 @@ public function process(&$request)
         $groups = [];
 
         $user = $this->adapter->getPerunUser($idpEntityId, $uids);
+        if ($this->useAdditionalIdentifiersLookup && null === $user) {
+            $additionalIdentifiers = $request[PerunConstants::ATTRIBUTES][$this->additionalIdentifiersAttribute] ?? null;
+            if (empty($additionalIdentifiers)) {
+                throw new Exception(
+                    'perun:PerunIdentity: missing mandatory attribute [' . $this->additionalIdentifiersAttribute . '] in request.'
+                );
+            }
+            $user = $this->adapter->getPerunUserByAdditionalIdentifiers($idpEntityId, $additionalIdentifiers);
+        }
 
         if (self::MODE_FULL === $this->mode) {
             $this->getSPAttributes($this->spEntityId);

lib/Auth/Process/PerunUser.php

@@ -38,13 +38,17 @@ class PerunUser extends ProcessingFilter
     public const REGISTER_URL = 'register_url';
     public const CALLBACK_PARAMETER_NAME = 'callback_parameter_name';
     public const PERUN_REGISTER_URL = 'perun_register_url';
+    public const USE_ADDITIONAL_IDENTIFIERS_LOOKUP = 'use_additional_identifiers_lookup';
+    public const ADDITIONAL_IDENTIFIERS_ATTRIBUTE = 'additional_identifiers_attribute';
 
     private $adapter;
     private $idpEntityIdAttr;
     private $userIdAttrs;
     private $registerUrl;
     private $callbackParameterName;
     private $perunRegisterUrl;
+    private $useAdditionalIdentifiersLookup;
+    private $additionalIdentifiersAttribute;
     private $config;
     private $filterConfig;
 
@@ -78,6 +82,19 @@ public function __construct($config, $reserved)
                 . If you wish to use the Perun registrar, use the option \'' . self::PERUN_REGISTER_URL . '\'.'
             );
         }
+        $this->useAdditionalIdentifiersLookup = $this->filterConfig->getBoolean(
+            self::USE_ADDITIONAL_IDENTIFIERS_LOOKUP,
+            false
+        );
+        $this->additionalIdentifiersAttribute = $this->filterConfig->getString(
+            self::ADDITIONAL_IDENTIFIERS_ATTRIBUTE,
+            null
+        );
+        if ($this->useAdditionalIdentifiersLookup && null === $this->additionalIdentifiersAttribute) {
+            throw new Exception(
+                self::DEBUG_PREFIX . 'Invalid configuration: no attribute configured for extracting additional identifiers. Use option \'' . self::ADDITIONAL_IDENTIFIERS_ATTRIBUTE . '\' to configure the name of the attribute, that should be considered as additional identifiers of the user.'
+            );
+        }
     }
 
     public function process(&$request)
@@ -107,6 +124,15 @@ public function process(&$request)
         }
 
         $user = $this->adapter->getPerunUser($idpEntityId, $uids);
+        if ($this->useAdditionalIdentifiersLookup && null === $user) {
+            $additionalIdentifiers = $request[PerunConstants::ATTRIBUTES][$this->additionalIdentifiersAttribute] ?? null;
+            if (empty($additionalIdentifiers)) {
+                throw new Exception(
+                    self::DEBUG_PREFIX . 'missing mandatory attribute [' . $this->additionalIdentifiersAttribute . '] in request.'
+                );
+            }
+            $user = $this->adapter->getPerunUserByAdditionalIdentifiers($idpEntityId, $additionalIdentifiers);
+        }
 
         if (!empty($user)) {
             $this->processUser($request, $user, $uids);