[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  namespace enrol_lti\local\ltiadvantage\entity;
  18  
  19  /**
  20   * Class application_registration.
  21   *
  22   * This class represents an LTI Advantage Application Registration.
  23   * Each registered application may contain one or more deployments of the Moodle tool.
  24   * This registration provides the security contract for all tool deployments belonging to the registration.
  25   *
  26   * @package enrol_lti
  27   * @copyright 2021 Jake Dallimore <jrhdallimore@gmail.com>
  28   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  29   */
  30  class application_registration {
  31  
  32      /** @var int|null the if of this registration instance, or null if it hasn't been stored yet. */
  33      private $id;
  34  
  35      /** @var string the name of the application being registered. */
  36      private $name;
  37  
  38      /** @var \moodle_url the issuer identifying the platform, as provided by the platform. */
  39      private $platformid;
  40  
  41      /** @var string the client id as provided by the platform. */
  42      private $clientid;
  43  
  44      /** @var \moodle_url the authentication request URL, as provided by the platform. */
  45      private $authenticationrequesturl;
  46  
  47      /** @var \moodle_url the certificate URL, as provided by the platform. */
  48      private $jwksurl;
  49  
  50      /** @var \moodle_url the access token URL, as provided by the platform. */
  51      private $accesstokenurl;
  52  
  53      /** @var string a unique identifier used by the registration in the initiate_login_uri to act as registration identifier.*/
  54      private $uniqueid;
  55  
  56      /** @var int status of the registration, either incomplete (draft) or complete (all required data present). */
  57      private $status;
  58  
  59      /** @var int const representing the incomplete state */
  60      const REGISTRATION_STATUS_INCOMPLETE = 0;
  61  
  62      /** @var int const representing a complete state */
  63      const REGISTRATION_STATUS_COMPLETE = 1;
  64  
  65      /**
  66       * The application_registration constructor.
  67       *
  68       * @param string $name the descriptor for this application registration.
  69       * @param string $uniqueid a unique identifier for the registration used in place of client_id in the login URI.
  70       * @param \moodle_url|null $platformid the URL of application
  71       * @param string|null $clientid unique id for the client on the application
  72       * @param \moodle_url|null $authenticationrequesturl URL to send OIDC Auth requests to.
  73       * @param \moodle_url|null $jwksurl URL to use to get public keys from the application.
  74       * @param \moodle_url|null $accesstokenurl URL to use to get an access token from the application, used in service calls.
  75       * @param int|null $id the id of the object instance, if being created from an existing store item.
  76       */
  77      private function __construct(string $name, string $uniqueid, ?\moodle_url $platformid, ?string $clientid,
  78              ?\moodle_url $authenticationrequesturl, ?\moodle_url $jwksurl, ?\moodle_url $accesstokenurl, int $id = null) {
  79  
  80          if (empty($name)) {
  81              throw new \coding_exception("Invalid 'name' arg. Cannot be an empty string.");
  82          }
  83          if (empty($uniqueid)) {
  84              throw new \coding_exception("Invalid 'uniqueid' arg. Cannot be an empty string.");
  85          }
  86  
  87          // Resolve the registration status.
  88          $iscomplete = (!is_null($platformid) && !is_null($clientid) && !is_null($authenticationrequesturl) &&
  89              !is_null($authenticationrequesturl) && !is_null($jwksurl) && !is_null($accesstokenurl));
  90          $this->status = $iscomplete ? self::REGISTRATION_STATUS_COMPLETE : self::REGISTRATION_STATUS_INCOMPLETE;
  91  
  92          $this->name = $name;
  93          $this->uniqueid = $uniqueid;
  94          $this->platformid = $platformid;
  95          $this->clientid = $clientid;
  96          $this->authenticationrequesturl = $authenticationrequesturl;
  97          $this->jwksurl = $jwksurl;
  98          $this->accesstokenurl = $accesstokenurl;
  99          $this->id = $id;
 100      }
 101  
 102      /**
 103       * Factory method to create a new instance of an application registration
 104       *
 105       * @param string $name the descriptor for this application registration.
 106       * @param string $uniqueid a unique identifier for the registration used in place of client_id in the login URI.
 107       * @param \moodle_url $platformid the URL of application
 108       * @param string $clientid unique id for the client on the application
 109       * @param \moodle_url $authenticationrequesturl URL to send OIDC Auth requests to.
 110       * @param \moodle_url $jwksurl URL to use to get public keys from the application.
 111       * @param \moodle_url $accesstokenurl URL to use to get an access token from the application, used in service calls.
 112       * @param int|null $id the id of the object instance, if being created from an existing store item.
 113       * @return application_registration the application_registration instance.
 114       * @throws \coding_exception if an invalid clientid is provided.
 115       */
 116      public static function create(string $name, string $uniqueid, \moodle_url $platformid, string $clientid,
 117              \moodle_url $authenticationrequesturl, \moodle_url $jwksurl, \moodle_url $accesstokenurl,
 118              int $id = null): application_registration {
 119  
 120          if (empty($clientid)) {
 121              throw new \coding_exception("Invalid 'clientid' arg. Cannot be an empty string.");
 122          }
 123  
 124          return new self($name, $uniqueid, $platformid, $clientid, $authenticationrequesturl, $jwksurl, $accesstokenurl, $id);
 125      }
 126  
 127      /**
 128       * Factory method to create a draft application registration.
 129       *
 130       * @param string $name the descriptor for the draft application registration.
 131       * @param string $uniqueid a unique identifier for the registration used in place of client_id in the login URI.
 132       * @param int|null $id the id of the object instance, if being created from an existing store item.
 133       * @return application_registration the application_registration instance.
 134       */
 135      public static function create_draft(string $name, string $uniqueid, int $id = null): application_registration {
 136          return new self($name, $uniqueid, null, null, null, null, null, $id);
 137      }
 138  
 139      /**
 140       * Get the integer id of this object instance.
 141       *
 142       * Will return null if the instance has not yet been stored.
 143       *
 144       * @return null|int the id, if set, otherwise null.
 145       */
 146      public function get_id(): ?int {
 147          return $this->id;
 148      }
 149  
 150      /**
 151       * Get the name of the application being registered.
 152       *
 153       * @return string the name.
 154       */
 155      public function get_name(): string {
 156          return $this->name;
 157      }
 158  
 159      /**
 160       * Sets the name of this registration.
 161       *
 162       * @param string $name the new name to set.
 163       * @throws \coding_exception if the provided name is invalid.
 164       */
 165      public function set_name(string $name): void {
 166          if (empty($name)) {
 167              throw new \coding_exception("Invalid 'name' arg. Cannot be an empty string.");
 168          }
 169          $this->name = $name;
 170      }
 171  
 172      /**
 173       * Return the local unique client id of the registration.
 174       *
 175       * @return string the id.
 176       */
 177      public function get_uniqueid(): string {
 178          return $this->uniqueid;
 179      }
 180  
 181      /**
 182       * Get the platform id.
 183       *
 184       * @return \moodle_url|null the platformid/issuer URL.
 185       */
 186      public function get_platformid(): ?\moodle_url {
 187          return $this->platformid;
 188      }
 189  
 190      /**
 191       * Sets the platformid/issuer for this registration.
 192       *
 193       * @param \moodle_url $platformid the platform id / iss to set.
 194       */
 195      public function set_platformid(\moodle_url $platformid): void {
 196          $this->platformid = $platformid;
 197      }
 198  
 199      /**
 200       * Get the client id.
 201       *
 202       * @return string|null the client id.
 203       */
 204      public function get_clientid(): ?string {
 205          return $this->clientid;
 206      }
 207  
 208      /**
 209       * Sets the client id for this registration.
 210       *
 211       * @param string $clientid the client id
 212       * @throws \coding_exception if the client id is invalid.
 213       */
 214      public function set_clientid(string $clientid): void {
 215          if (empty($clientid)) {
 216              throw new \coding_exception("Invalid 'clientid' arg. Cannot be an empty string.");
 217          }
 218          $this->clientid = $clientid;
 219      }
 220  
 221      /**
 222       * Get the authentication request URL.
 223       *
 224       * @return \moodle_url|null the authentication request URL.
 225       */
 226      public function get_authenticationrequesturl(): ?\moodle_url {
 227          return $this->authenticationrequesturl;
 228      }
 229  
 230      /**
 231       * Sets the authentication request URL for this registration.
 232       *
 233       * @param \moodle_url $authenticationrequesturl the authentication request URL.
 234       */
 235      public function set_authenticationrequesturl(\moodle_url $authenticationrequesturl): void {
 236          $this->authenticationrequesturl = $authenticationrequesturl;
 237      }
 238  
 239      /**
 240       * Get the JWKS URL.
 241       *
 242       * @return \moodle_url|null the JWKS URL.
 243       */
 244      public function get_jwksurl(): ?\moodle_url {
 245          return $this->jwksurl;
 246      }
 247  
 248      /**
 249       * Sets the JWKS URL for this registration.
 250       *
 251       * @param \moodle_url $jwksurl the JWKS URL.
 252       */
 253      public function set_jwksurl(\moodle_url $jwksurl): void {
 254          $this->jwksurl = $jwksurl;
 255      }
 256  
 257      /**
 258       * Get the access token URL.
 259       *
 260       * @return \moodle_url|null the access token URL.
 261       */
 262      public function get_accesstokenurl(): ?\moodle_url {
 263          return $this->accesstokenurl;
 264      }
 265  
 266      /**
 267       * Sets the access token URL for this registration.
 268       *
 269       * @param \moodle_url $accesstokenurl the access token URL.
 270       */
 271      public function set_accesstokenurl(\moodle_url $accesstokenurl): void {
 272          $this->accesstokenurl = $accesstokenurl;
 273      }
 274  
 275      /**
 276       * Add a tool deployment to this registration.
 277       *
 278       * @param string $name human readable name for the deployment.
 279       * @param string $deploymentid the unique id of the tool deployment in the platform.
 280       * @return deployment the new deployment.
 281       * @throws \coding_exception if trying to add a deployment to an instance without an id assigned.
 282       */
 283      public function add_tool_deployment(string $name, string $deploymentid): deployment {
 284  
 285          if (empty($this->get_id())) {
 286              throw new \coding_exception("Can't add deployment to a resource_link that hasn't first been saved.");
 287          }
 288  
 289          return deployment::create(
 290              $this->get_id(),
 291              $deploymentid,
 292              $name
 293          );
 294      }
 295  
 296      /**
 297       * Check whether this registration is complete or not.
 298       */
 299      public function is_complete(): bool {
 300          return $this->status == self::REGISTRATION_STATUS_COMPLETE;
 301      }
 302  
 303      /**
 304       * Attempt to progress this registration to the 'complete' state, provided required state exists.
 305       *
 306       * @see REGISTRATION_STATUS_COMPLETE
 307       *
 308       * @throws \coding_exception if the registration isn't in a state to be transitioned to complete.
 309       */
 310      public function complete_registration(): void {
 311          // Check completeness of registration.
 312          if (is_null($this->platformid)) {
 313              throw new \coding_exception("Unable to complete registration. Platform ID is missing.");
 314          }
 315          if (is_null($this->clientid)) {
 316              throw new \coding_exception("Unable to complete registration. Client ID is missing.");
 317          }
 318          if (is_null($this->accesstokenurl)) {
 319              throw new \coding_exception("Unable to complete registration. Access token URL is missing.");
 320          }
 321          if (is_null($this->authenticationrequesturl)) {
 322              throw new \coding_exception("Unable to complete registration. Authentication request URL is missing.");
 323          }
 324          if (is_null($this->jwksurl)) {
 325              throw new \coding_exception("Unable to complete registration. JWKS URL is missing.");
 326          }
 327          $this->status = self::REGISTRATION_STATUS_COMPLETE;
 328      }
 329  }