feat: 🎸 AuthProcFilter PerunUser - identify user from Perun

Author: Dominik Frantisek Bucik

config-templates/processFilterConfigurations-example.md

@@ -179,5 +179,28 @@ Configuration options:
     'fail_on_nonexisting_keys' => 'true',
     'default_value' => null,
 ],
+```
+
+## PerunUser
 
+Filter tries to identify the Perun user. It uses the combination of user identifier and IdP identifier to find the user (or to be more precise, the user identity and associated user account). If it can, the user object is set to `$request` parameter into `$request[PerunConstants::PERUN][PerunConstants::USER]`. Otherwise, user is forwarded to configured registration.
+
+Configuration options:
+* `interface`: specifies what interface of Perun should be used to fetch data. See class `SimpleSAML\Module\perun\PerunAdapter` for more details.
+* `uid_attrs`: list of attributes that contain user identifiers to be used for identification. The order of the items in the list represents the priority.
+* `idp_id_attr`: name of the attribute (from `$request['Attributes']` array), which holds EntityID of the identity provider that has performed the authentication.
+* `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.
+
+```php
+2 => [
+    'class' => 'perun:PerunUser',
+    'interface' => 'LDAP',
+    'uid_attrs' => ['eduPersonUniqueId', 'eduPersonPrincipalName'],
+    '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'
+],
 ```

dictionaries/perun.definition.json

@@ -94,5 +94,13 @@
   "unauthorized-access_redirect_to_registration": {
     "en": "Now you will be redirected to registration to Perun system.",
     "cs": "Nyní budete přesměrování na registraci do systému Perun."
+  },
+  "register_text": {
+    "en": "Oops! It seems you have tried to access service via Perun AAI, but yo do not have an account. Let's fix that!",
+    "cs": "Ups! Zdá se, že jste se pokusil(a) přihlásit ke službě skrz Perun AAI, no nemáte uživatelský účet. Pojďme to napravit!"
+  },
+  "register_button": {
+    "en": "Proceed to register for an account",
+    "cs": "Pokračovat na registraci ůčtu"
   }
 }

lib/Adapter.php

@@ -48,7 +48,7 @@ public static function getInstance($interface)
 
     /**
      * @param string $idpEntityId entity id of hosted idp used as extSourceName
-     * @param string $uids        list of user identifiers received from remote idp used as userExtSourceLogin
+     * @param array  $uids        list of user identifiers received from remote idp used as userExtSourceLogin
      *
      * @return User or null if not exists
      */

lib/Auth/Process/PerunUser.php

@@ -0,0 +1,174 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleSAML\Module\perun\Auth\Process;
+
+use SimpleSAML\Auth\ProcessingFilter;
+use SimpleSAML\Auth\State;
+use SimpleSAML\Configuration;
+use SimpleSAML\Error\Exception;
+use SimpleSAML\Logger;
+use SimpleSAML\Module;
+use SimpleSAML\Module\perun\Adapter;
+use SimpleSAML\Module\perun\model\User;
+use SimpleSAML\Module\perun\PerunConstants;
+use SimpleSAML\Utils\HTTP;
+
+/**
+ * Class tries to find user in Perun using the extLogin and extSourceName (in case of RPC adapter).
+ *
+ * If the user cannot be found, it redirects user to the registration URL.
+ */
+class PerunUser extends ProcessingFilter
+{
+    public const STAGE = 'perun:PerunUser';
+    public const DEBUG_PREFIX = self::STAGE . ' - ';
+
+    public const CALLBACK = 'perun/perun_user_callback.php';
+    public const REDIRECT = 'perun/perun_user.php';
+    public const TEMPLATE = 'perun:perun-user-tpl.php';
+
+    public const PARAM_REGISTRATION_URL = 'registrationUrl';
+    public const PARAM_STATE_ID = PerunConstants::STATE_ID;
+
+    public const INTERFACE = 'interface';
+    public const UID_ATTRS = 'uid_attrs';
+    public const IDP_ID_ATTR = 'idp_id_attr';
+    public const REGISTER_URL = 'register_url';
+    public const CALLBACK_PARAMETER_NAME = 'callback_parameter_name';
+    public const PERUN_REGISTER_URL = 'perun_register_url';
+
+    private $adapter;
+    private $idpEntityIdAttr;
+    private $userIdAttrs;
+    private $registerUrl;
+    private $callbackParameterName;
+    private $perunRegisterUrl;
+    private $config;
+    private $filterConfig;
+
+    public function __construct($config, $reserved)
+    {
+        parent::__construct($config, $reserved);
+        $this->config = $config;
+        $this->filterConfig = Configuration::loadFromArray($config);
+
+        $interface = $this->filterConfig->getString(self::INTERFACE, Adapter::RPC);
+
+        $this->adapter = Adapter::getInstance($interface);
+        $this->userIdAttrs = $this->filterConfig->getArray(self::UID_ATTRS, []);
+        if (empty($this->userIdAttrs)) {
+            throw new Exception(
+                self::DEBUG_PREFIX . 'Invalid configuration: no attributes configured for ' . 'extracting UID. Use option \'' . self::UID_ATTRS . '\' to configure list of attributes, ' . 'that should be considered as IDs for a user'
+            );
+        }
+        $this->idpEntityIdAttr = $this->filterConfig->getString(self::IDP_ID_ATTR, null);
+        if (empty($this->idpEntityIdAttr)) {
+            throw new Exception(
+                self::DEBUG_PREFIX . 'Invalid configuration: no attribute containing IDP ' . 'ID has been configured. Use option \'' . self::IDP_ID_ATTR . '\' to configure the name of the ' . 'attribute, that has been previously used in the configuration of filter \'perun:ExtractIdpEntityId\''
+            );
+        }
+        $this->registerUrl = $this->filterConfig->getString(self::REGISTER_URL, null);
+        $this->callbackParameterName = $this->filterConfig->getString(self::CALLBACK_PARAMETER_NAME, null);
+        $this->perunRegisterUrl = $this->filterConfig->getString(self::PERUN_REGISTER_URL, null);
+        if (empty($this->registerUrl) && empty($this->callbackParameterName) && empty($this->perunRegisterUrl)) {
+            throw new Exception(
+                self::DEBUG_PREFIX . 'Invalid configuration: no URL where user should register for the ' . 'account has been configured. Use option \'' . self::REGISTER_URL . '\' to configure the URL and ' . 'option \'' . self::CALLBACK_PARAMETER_NAME . '\' to configure name of the callback parameter. 
+                . If you wish to use the Perun registrar, use the option \'' . self::PERUN_REGISTER_URL . '\'.'
+            );
+        }
+    }
+
+    public function process(&$request)
+    {
+        assert(is_array($request));
+        assert(array_key_exists(PerunConstants::ATTRIBUTES, $request));
+
+        $uids = [];
+        foreach ($this->userIdAttrs as $uidAttr) {
+            if (isset($request[PerunConstants::ATTRIBUTES][$uidAttr][0])) {
+                $uids[] = $request[PerunConstants::ATTRIBUTES][$uidAttr][0];
+            }
+        }
+        if (empty($uids)) {
+            throw new Exception(self::DEBUG_PREFIX . 'missing at least one of mandatory attributes [' . implode(
+                ', ',
+                $this->userIdAttrs
+            ) . '] in request.');
+        }
+
+        if (!empty($request[PerunConstants::ATTRIBUTES][$this->idpEntityIdAttr][0])) {
+            $idpEntityId = $request[PerunConstants::ATTRIBUTES][$this->idpEntityIdAttr][0];
+        } else {
+            throw new Exception(
+                self::DEBUG_PREFIX . 'Cannot find entityID of source IDP. Did you properly configure ' . ExtractRequestAttribute::STAGE . ' filter before this filter in the processing chain?'
+            );
+        }
+
+        $user = $this->adapter->getPerunUser($idpEntityId, $uids);
+
+        if (!empty($user)) {
+            Logger::debug(self::DEBUG_PREFIX . 'User identified, setting Perun user into request.');
+            $this->processUser($request, $user, $uids);
+
+            return;
+        }
+        Logger::debug(self::DEBUG_PREFIX . 'User not identified, redirecting to registration.');
+        $this->register($request, $uids);
+    }
+
+    private function processUser(array &$request, User $user, array $uids): void
+    {
+        if (!isset($request[PerunConstants::PERUN])) {
+            $request[PerunConstants::PERUN] = [];
+        }
+
+        $request[PerunConstants::PERUN][PerunConstants::USER] = $user;
+
+        Logger::info(
+            self::DEBUG_PREFIX . 'Perun user with identity/ies: ' . implode(',', $uids)
+            . ' has been found. Setting user ' . $user->getName() . ' with id: ' . $user->getId() . ' to the request.'
+        );
+    }
+
+    private function register(array &$request, array $uids): void
+    {
+        $request[PerunConstants::CONTINUE_FILTER_CONFIG] = $this->config;
+        $stateId = State::saveState($request, self::STAGE);
+        $callback = Module::getModuleURL(self::CALLBACK, [
+            self::PARAM_STATE_ID => $stateId,
+        ]);
+        Logger::debug(self::DEBUG_PREFIX . 'Produced callback URL \'' . $callback . '\'');
+
+        if (!empty($this->registerUrl) && !empty($this->callbackParameterName)) {
+            Logger::debug(
+                self::DEBUG_PREFIX . 'Redirecting to \'' . $this->registerUrl . ', callback parameter \''
+                . $this->callbackParameterName . '\' with value \'' . $callback . '\''
+            );
+            HTTP::redirectTrustedURL($this->registerUrl, [
+                $this->callbackParameterName => $callback,
+            ]);
+        } elseif (!empty($this->perunRegisterUrl)) {
+            $params[PerunConstants::TARGET_NEW] = $callback;
+            $params[PerunConstants::TARGET_EXISTING] = $callback;
+            $params[PerunConstants::TARGET_EXTENDED] = $callback;
+
+            $url = Module::getModuleURL(self::REDIRECT);
+            $registrationUrl = HTTP::addURLParameters($this->perunRegisterUrl, $params);
+            Logger::debug(
+                self::DEBUG_PREFIX . 'Redirecting to \'' . self::REDIRECT . ', registration URL \''
+                . $registrationUrl . '\''
+            );
+            HTTP::redirectTrustedURL($url, [
+                self::PARAM_REGISTRATION_URL => $registrationUrl,
+            ]);
+        } else {
+            throw new Exception(self::DEBUG_PREFIX . 'No configuration for registration enabled. Cannot proceed');
+        }
+        Logger::info(
+            self::DEBUG_PREFIX . 'Perun user with identity/ies: ' . implode(',', $uids) .
+            ' has not been found. Redirecting to registration.'
+        );
+    }
+}

lib/PerunConstants.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace SimpleSAML\Module\perun;
 
 class PerunConstants
@@ -12,4 +14,14 @@ class PerunConstants
 
     public const TARGET_EXTENDED = 'targetextended';
 
+    public const PERUN = 'perun';
+
+    public const USER = 'user';
+
+    public const STATE_ID = 'stateId';
+
+    public const CONFIG = 'config';
+
+    public const CONTINUE_FILTER_CONFIG = 'continueFilterConfig';
+
 }

templates/perun-user-tpl.php

@@ -0,0 +1,21 @@
+<?php declare(strict_types=1);
+
+use SimpleSAML\Module\perun\Auth\Process\PerunUser;
+
+$this->includeAtTemplateBase('includes/header.php');
+
+?>
+
+<div class="row">
+    <div class="offset-1 col-10 offset-sm-1 col-sm-10 offset-md-2 col-md-8 offset-lg-3 col-lg-6 offset-xl-3 col-xl-6">
+        <p><?php echo $this->t('{perun:perun:register_text}'); ?></p>
+        <a class="btn btn-block" href="<?php echo $this->data[PerunUser::PARAM_REGISTRATION_URL]; ?>">
+            <?php echo $this->t('{perun:perun:register_button}'); ?>
+        </a>
+    </div>
+</div>
+
+
+<?php
+
+$this->includeAtTemplateBase('includes/footer.php');

www/perun_user.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use SimpleSAML\Configuration;
+use SimpleSAML\Module\perun\Auth\Process\PerunUser;
+use SimpleSAML\XHTML\Template;
+
+$config = Configuration::getInstance();
+$t = new Template($config, PerunUser::TEMPLATE);
+$t->data[PerunUser::PARAM_REGISTRATION_URL] = $_REQUEST[PerunUser::PARAM_REGISTRATION_URL];
+
+$t->show();

www/perun_user_callback.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+use SimpleSAML\Auth\ProcessingChain;
+use SimpleSAML\Auth\State;
+use SimpleSAML\Error\BadRequest;
+use SimpleSAML\Module\perun\Auth\Process\PerunUser;
+use SimpleSAML\Module\perun\PerunConstants;
+
+if (empty($_REQUEST[PerunUser::PARAM_STATE_ID])) {
+    throw new BadRequest('Missing required \'' . PerunUser::PARAM_STATE_ID . '\' query parameter.');
+}
+$state = State::loadState($_REQUEST[PerunUser::PARAM_STATE_ID], PerunUser::STAGE);
+
+$filterConfig = $state[PerunConstants::CONTINUE_FILTER_CONFIG];
+$perunUser = new PerunUser($filterConfig, null);
+$perunUser->process($state);
+
+// we have not been redirected, continue processing
+ProcessingChain::resumeProcessing($state);