Merge pull request #89 from oat-sa/develop

Develop

CHANGELOG.md

@@ -1,6 +1,13 @@
 CHANGELOG
 =========
 
+4.2.0
+-----
+
+* Added enhanced role management: type (system, institution, context), core / non core, long / short names & automatic validation
+* Updated LtiMessagePayloadInterface with getValidatedRoleCollection() method (allows easy access to validated roles from launches)
+* Updated documentation
+
 4.1.0
 -----
 

doc/message/platform-originating-messages.md

@@ -360,3 +360,39 @@ if (!$result->hasError()) {
     }
 } 
 ```
+
+### Working with launch roles
+
+The [LtiMessagePayloadInterface](../../src/Message/Payload/LtiMessagePayloadInterface.php) provides the `getValidatedRoleCollection()` getter to allow you to work easily with [the LTI specification roles](http://www.imsglobal.org/spec/lti/v1p3/#role-vocabularies) as a [RoleCollection](../../src/Role/Collection/RoleCollection.php).
+
+You can base yourself on this collection if you need to perform RBAC on tool side, for example:
+
+```php
+<?php
+
+use OAT\Library\Lti1p3Core\Message\Launch\Validator\Result\LaunchValidationResult;
+use OAT\Library\Lti1p3Core\Role\RoleInterface;
+
+/** @var LaunchValidationResult $result */
+$result = $validator->validatePlatformOriginatingLaunch(...);
+
+// Result exploitation
+if (!$result->hasError()) {
+
+    // Access the validated role collection
+    $roles = $result->getPayload()->getValidatedRoleCollection();
+
+    // Check if a role of type context (core or not) has been provided (our case for http://purl.imsglobal.org/vocab/lis/v2/membership#Learner)
+    if ($roles->canFindBy(RoleInterface::TYPE_CONTEXT)) {
+        // Authorized launch
+        ...
+    } else {
+        // Unauthorized launch
+        ...
+    }
+} 
+```
+
+**Notes**: 
+- if the launch contains invalid (non respecting LTI specification) roles, the getter will throw an [LtiException](../../src/Exception/LtiException.php)
+- the [LtiMessagePayloadInterface](../../src/Message/Payload/LtiMessagePayloadInterface.php) offers the `getRoles()` getter to work with plain roles values (no validation)

src/Message/Payload/LtiMessagePayload.php

@@ -36,6 +36,9 @@
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ProctoringSettingsClaim;
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ProctoringVerifiedUserClaim;
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ResourceLinkClaim;
+use OAT\Library\Lti1p3Core\Role\Collection\RoleCollection;
+use OAT\Library\Lti1p3Core\Role\Collection\RoleCollectionInterface;
+use OAT\Library\Lti1p3Core\Role\Factory\RoleFactory;
 use OAT\Library\Lti1p3Core\User\UserIdentity;
 use OAT\Library\Lti1p3Core\User\UserIdentityInterface;
 
@@ -84,6 +87,20 @@ public function getRoles(): array
         return $this->getMandatoryClaim(static::CLAIM_LTI_ROLES);
     }
 
+    /**
+     * @throws LtiExceptionInterface
+     */
+    public function getValidatedRoleCollection(): RoleCollection
+    {
+        $collection = new RoleCollection();
+
+        foreach ($this->getMandatoryClaim(static::CLAIM_LTI_ROLES) as $role) {
+            $collection->add(RoleFactory::create($role));
+        }
+
+        return $collection;
+    }
+
     public function getResourceLink(): ?ResourceLinkClaim
     {
         return $this->getClaim(ResourceLinkClaim::class);

src/Message/Payload/LtiMessagePayloadInterface.php

@@ -35,6 +35,7 @@
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ProctoringSettingsClaim;
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ProctoringVerifiedUserClaim;
 use OAT\Library\Lti1p3Core\Message\Payload\Claim\ResourceLinkClaim;
+use OAT\Library\Lti1p3Core\Role\Collection\RoleCollection;
 use OAT\Library\Lti1p3Core\User\UserIdentityInterface;
 
 /**
@@ -95,6 +96,8 @@ public function getTargetLinkUri(): string;
 
     public function getRoles(): array;
 
+    public function getValidatedRoleCollection(): RoleCollection;
+
     public function getRoleScopeMentor(): array;
 
     public function getCustom(): array;

src/Role/AbstractRole.php

@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace OAT\Library\Lti1p3Core\Role;
+
+use OAT\Library\Lti1p3Core\Exception\LtiException;
+use OAT\Library\Lti1p3Core\Exception\LtiExceptionInterface;
+
+abstract class AbstractRole implements RoleInterface
+{
+    /** @var string */
+    protected $name;
+
+    /**
+     * @throws LtiExceptionInterface
+     */
+    public function __construct(string $name)
+    {
+        $this->name = $name;
+
+        if (!$this->isValid()) {
+            throw new LtiException(sprintf('Role %s is invalid for type %s', $this->name, static::getType()));
+        }
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getSubName(): ?string
+    {
+        return null;
+    }
+
+    public function isCore(): bool
+    {
+        $exp = explode('#', $this->name);
+
+        return $this->getMap()[end($exp)];
+    }
+
+    protected function isValid(): bool
+    {
+        if (strpos($this->name, static::getNamespace()) !== 0) {
+            return false;
+        }
+
+        $exp = explode('#', $this->name);
+
+        return array_key_exists(end($exp), $this->getMap());
+    }
+
+    abstract protected function getMap(): array;
+}

src/Role/Collection/RoleCollection.php

@@ -0,0 +1,100 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace OAT\Library\Lti1p3Core\Role\Collection;
+
+use OAT\Library\Lti1p3Core\Role\RoleInterface;
+use OAT\Library\Lti1p3Core\Util\Collection\Collection;
+use OAT\Library\Lti1p3Core\Util\Collection\CollectionInterface;
+
+class RoleCollection
+{
+    /** @var RoleInterface[]|CollectionInterface */
+    private $roles;
+
+    public function __construct(array $roles = [])
+    {
+        $this->roles = new Collection();
+
+        foreach ($roles as $role) {
+            $this->add($role);
+        }
+    }
+
+    public function all(): array
+    {
+        return $this->roles->all();
+    }
+
+    public function count(): int
+    {
+        return $this->roles->count();
+    }
+
+    public function add(RoleInterface $role): self
+    {
+        $this->roles->set($role->getName(), $role);
+
+        return $this;
+    }
+
+    public function has(string $name): bool
+    {
+        return $this->roles->has($name);
+    }
+
+    public function get(string $name): RoleInterface
+    {
+        return $this->roles->getMandatory($name);
+    }
+
+    public function canFindBy(?string $type = null, ?bool $core = null): bool
+    {
+        return !empty($this->findBy($type, $core));
+    }
+
+    /**
+     * @return RoleInterface[]
+     */
+    public function findBy(?string $type = null, ?bool $core = null): array
+    {
+        $roles = [];
+
+        foreach ($this->roles as $name => $role) {
+             $add = true;
+
+            if (null !== $type) {
+                $add = $add && $role::getType() === $type;
+            }
+
+            if (null !== $core) {
+                $add = $add && $role->isCore() === $core;
+            }
+
+            if ($add) {
+                $roles[$name] = $role;
+            }
+        }
+
+        return $roles;
+    }
+}

src/Role/Factory/RoleFactory.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace OAT\Library\Lti1p3Core\Role\Factory;
+
+use OAT\Library\Lti1p3Core\Exception\LtiExceptionInterface;
+use OAT\Library\Lti1p3Core\Role\RoleInterface;
+use OAT\Library\Lti1p3Core\Role\Type\ContextRole;
+use OAT\Library\Lti1p3Core\Role\Type\InstitutionRole;
+use OAT\Library\Lti1p3Core\Role\Type\SystemRole;
+
+class RoleFactory
+{
+    /**
+     * @throws LtiExceptionInterface
+     */
+    public static function create(string $name): RoleInterface
+    {
+        if (strpos($name, SystemRole::getNameSpace()) === 0) {
+            return new SystemRole($name);
+        }
+
+        if (strpos($name, InstitutionRole::getNameSpace()) === 0) {
+            return new InstitutionRole($name);
+        }
+
+        return new ContextRole($name);
+    }
+}

src/Role/RoleInterface.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace OAT\Library\Lti1p3Core\Role;
+
+/**
+ * @see http://www.imsglobal.org/spec/lti/v1p3/#role-vocabularies
+ */
+interface RoleInterface
+{
+    public const TYPE_SYSTEM = 'system';
+    public const TYPE_INSTITUTION = 'institution';
+    public const TYPE_CONTEXT = 'context';
+
+    public const NAMESPACE_SYSTEM = 'http://purl.imsglobal.org/vocab/lis/v2/system/person';
+    public const NAMESPACE_INSTITUTION = 'http://purl.imsglobal.org/vocab/lis/v2/institution/person';
+    public const NAMESPACE_CONTEXT = 'http://purl.imsglobal.org/vocab/lis/v2/membership';
+
+    public static function getType(): string;
+
+    public static function getNamespace(): string;
+
+    public function getName(): string;
+
+    public function getSubName(): ?string;
+
+    public function isCore(): bool;
+}