Add documentation and resource server tests

.gitignore

@@ -8,3 +8,4 @@ node_modules
 /var
 .ddev/*adminer*
 .ddev/addon-metadata
+/Documentation-GENERATED-temp

Build/Scripts/genDocs.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation

Classes/Domain/Factory/AuthorizationServerFactory.php

@@ -145,7 +145,7 @@ protected function getAuthCodeGrant(Configuration $configuration): AuthCodeGrant
 
     protected function getImplicitGrant(Configuration $configuration): ImplicitGrant
     {
-        $accessTokenTTL = new \DateInterval('PT1H');
+        $accessTokenTTL = new \DateInterval($configuration->getAccessTokensExpireIn());
         return GeneralUtility::makeInstance(ImplicitGrant::class, $accessTokenTTL);
     }
 

Classes/Middleware/Dispatcher.php

@@ -41,7 +41,7 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             return $handler->handle($request);
         }
 
-        $expressions = (array)($route->getOptions()['oauth2_constraints'] ?? 'null != request.getAttribute("oauth_access_token_id")');
+        $expressions = (array)($route->getOptions()['oauth2_constraints'] ?? 'oauth.authorized');
         try {
             $this->checkConstraints($request, $expressions);
         } catch (\Exception $exception) {
@@ -78,6 +78,7 @@ private function checkConstraints(ServerRequestInterface $request, array $expres
         $oauth = new \stdClass();
         $oauth->authorized = $request->getAttribute(RequestAttributes::OAUTH_ACCESS_TOKEN_ID) !== null;
         $oauth->grant = $request->getAttribute(RequestAttributes::OAUTH2_GRANT)?->value;
+        $oauth->scopes = $request->getAttribute(RequestAttributes::OAUTH_SCOPES);
         $variables['oauth'] = $oauth;
 
         $variables['request'] = $request;

Classes/Middleware/Initializer.php

@@ -100,5 +100,6 @@ private function updateGlobalConfiguration(): void
     {
         $GLOBALS['TYPO3_CONF_VARS']['SVCONF']['auth']['setup']['FE_fetchUserIfNoSession'] = true;
         $GLOBALS['TYPO3_CONF_VARS']['FE']['checkFeUserPid'] = false;
+        $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash']['excludedParameters'][] = 'logintype';
     }
 }

Classes/RequestAttributes.php

@@ -9,4 +9,5 @@ final class RequestAttributes
     public const OAUTH2_ROUTE = 'oauth2.route';
     public const OAUTH2_GRANT = 'oauth2.grant';
     public const OAUTH_ACCESS_TOKEN_ID = 'oauth_access_token_id';
+    public const OAUTH_SCOPES = 'oauth_scopes';
 }

Classes/Routing/ResourceRouter.php

@@ -35,8 +35,12 @@ protected function getRoutes(): RouteCollection
 
         $routes = new RouteCollection();
         foreach ($resources as $resource) {
-            $loader = new YamlFileLoader(new FileLocator($resource));
-            $routes->addCollection($loader->load('routes.yaml'));
+            $pathInfo = pathinfo($resource);
+            if (!isset($pathInfo['dirname'])) {
+                throw new \RuntimeException('Invalid resource path', 1719953871204);
+            }
+            $loader = new YamlFileLoader(new FileLocator($pathInfo['dirname']));
+            $routes->addCollection($loader->load($pathInfo['basename']));
         }
 
         $event = new ModifyResourceServerRoutesEvent($this->configuration, $routes);

Documentation/Configuration/Index.rst

@@ -0,0 +1,108 @@
+..  include:: /Includes.rst.txt
+
+..  _configuration:
+
+=============
+Configuration
+=============
+
+..  warning::
+    **Use the provided key pair only for development and testing purposes!**
+    Check the :ref:`quick start section <quickConfiguration>` for information on how to create your own key pair.
+
+..  confval:: privateKey
+    :name: oauth2-privateKey
+    :type: string
+    :required: true
+    :default: EXT:oauth2_server/Resources/Private/Keys/private.key
+    :Path: Site configuration :yaml:`oauth2.privateKey` or extension configuration :php:`$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_server']['privateKey']`
+
+    Path to the private key file.
+
+..  confval:: publicKey
+    :name: oauth2-publicKey
+    :type: string
+    :required: true
+    :default: EXT:oauth2_server/Resources/Private/Keys/public.key
+    :Path: Site configuration :yaml:`oauth2.publicKey` or extension configuration :php:`$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_server']['publicKey']`
+
+    Path to the public key file.
+
+..  confval:: routePrefix
+    :name: oauth2-routePrefix
+    :type: string
+    :required: false
+    :default: oauth2
+    :Path: Site configuration :yaml:`oauth2.routePrefix`
+
+    Prefix for the OAuth2 server routes.
+
+..  confval:: accessTokensExpireIn
+    :name: oauth2-accessTokensExpireIn
+    :type: string
+    :required: false
+    :default: PT1H
+    :Path: Site configuration :yaml:`oauth2.accessTokensExpireIn`
+
+    Access token lifetime, default is 1 hour.
+
+..  confval:: refreshTokensExpireIn
+    :name: oauth2-refreshTokensExpireIn
+    :type: string
+    :required: false
+    :default: P1M
+    :Path: Site configuration :yaml:`oauth2.refreshTokensExpireIn`
+
+    Refresh token lifetime, default is 1 month.
+
+..  confval:: requireCodeChallengeForPublicClients
+    :name: oauth2-requireCodeChallengeForPublicClients
+    :type: string
+    :required: false
+    :default: true
+    :Path: Site configuration :yaml:`oauth2.requireCodeChallengeForPublicClients`
+
+    Requires code challenge for public clients by default.
+
+..  confval:: consentPageUid
+    :name: oauth2-consentPageUid
+    :type: string
+    :required: true
+    :default: null
+    :Path: Site configuration :yaml:`oauth2.consentPageUid` or extension configuration :php:`$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_server']['consentPageUid']`
+
+    Page UID of the consent page.
+
+..  confval:: loginPageUid
+    :name: oauth2-loginPageUid
+    :type: string
+    :required: true
+    :default: null
+    :Path: Site configuration :yaml:`oauth2.loginPageUid` or extension configuration :php:`$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_server']['loginPageUid']`
+
+    Page UID of the login page.
+
+..  confval:: scopes
+    :name: oauth2-scopes
+    :type: string
+    :required: false
+    :default: []
+    :Path: Site configuration :yaml:`oauth2.scopes`
+
+    List of scopes.
+
+..  confval:: resources
+    :name: oauth2-resources
+    :type: string
+    :required: false
+    :default: []
+    :Path: Site configuration :yaml:`oauth2.resources`
+
+    List of yaml configuration files with :ref:`resource routes <resourceRoutes>`.
+
+..  toctree::
+   :maxdepth: 5
+   :titlesonly:
+   :hidden:
+
+   ResourceRoutes

Documentation/Configuration/ResourceRoutes.rst

@@ -0,0 +1,79 @@
+..  include:: /Includes.rst.txt
+
+..  _resourceRoutes:
+
+============================
+Resource route configuration
+============================
+
+Routing is handled by `Symfony's routing component <https://symfony.com/doc/current/routing.html#creating-routes>`__. The configuration is done in YAML files.
+
+For every route you can configure some access restrictions by defining the option :code:`oauth2_constraints`.
+
+..  confval:: oauth2_constraints
+    :name: route-oauth2_constraints
+    :type: string|array
+    :required: false
+    :default: oauth.authorized
+    :Path: Route configuration :yaml:`[route].options.oauth2_constraints`
+
+    One or more access constraints for the route. The constraints are combined with a logical AND.
+    The constraints are evaluated with the `Symfony Expression Language <https://symfony.com/doc/current/components/expression_language.html>`__.
+
+    The following variables are available:
+
+    ..  t3-field-list-table::
+        :header-rows: 1
+
+         -  :variable:      Variable
+            :type:          Type
+            :description:   Description
+
+         -  :variable:      frontend.*
+            :type:          object
+            :description:   Same as in https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/Conditions/Index.html#frontend
+
+         -  :variable:      oauth.authorized
+            :type:          boolean
+            :description:   True if authorization header was set and the token is valid
+
+         -  :variable:      oauth.grant
+            :type:          string
+            :description:   The grant type of the token
+
+         -  :variable:      oauth.scopes
+            :type:          array
+            :description:   The scopes of the token
+
+         -  :variable:      request
+            :type:          object
+            :description:   The server request object
+
+Examples
+========
+
+Register route for an endpoint which executes a controller action similiar to eID:
+
+..  code-block:: yaml
+
+    # EXT:my_extension/Configuration/Yaml/Routes.yaml
+    example-controller:
+        path: /api/v1/simple
+        controller: 'Namespace\\MyExtension\\Controller\\ExampleController::handleRequest'
+        methods: [GET, POST]
+        schemes: https
+
+Protect everything below a certain path and check if scope "read" is present:
+
+..  code-block:: yaml
+
+    # EXT:my_extension/Configuration/Yaml/Routes.yaml
+    my-protected-area:
+        path: /api/v1/{slug}
+        requirements:
+            slug: '.*'
+        options:
+            oauth2_constraints:
+                - 'oauth.authorized'
+                - '"read" in oauth.scopes'
+

Documentation/Developer/Index.rst

@@ -0,0 +1,108 @@
+..  include:: /Includes.rst.txt
+..  highlight:: php
+
+..  _developer:
+
+================
+Developer corner
+================
+
+Use this section to provide examples of code or detail any information that would be deemed relevant to a developer.
+
+For example explain how a certain feature was implemented.
+
+
+..  _developer-api:
+
+API
+===
+
+How to use the API...
+
+Interfaces
+----------
+
+The following list provides information for all necessary interfaces that are
+used inside of this documentation. For up to date information, please check
+the source code.
+
+
+..  php:namespace:: Vendor\MyExtension\Interfaces
+
+..  php:interface:: ExampleInterface
+
+    Has to be implemented by all ...
+
+    ..  php:method:: methodOne()
+
+        :returntype: string
+        :returns: Something important
+
+..  php:interface:: AnotherImportantInterface
+
+    Used for ...
+
+..  php:interface:: RequireJsModuleInterface
+
+    Widgets implementing this interface will add the provided RequireJS modules.
+    Those modules will be loaded in dashboard view if the widget is added at least once.
+
+    ..  php:method:: getRequireJsModules()
+
+        Returns a list of RequireJS modules that should be loaded, e.g.::
+
+            return [
+                'TYPO3/CMS/MyExtension/ModuleName',
+                'TYPO3/CMS/MyExtension/Module2Name',
+            ];
+
+        See also :ref:`t3coreapi:requirejs` for further information regarding RequireJS
+        in TYPO3 Backend.
+
+        :returntype: array
+        :returns: List of modules to require.
+
+    ..  php:method:: setDate($year, $month, $day)
+
+        Set the date.
+
+        :param int $year: The year.
+        :param int $month: The month.
+        :param int $day: The day.
+        :returns: Either false on failure, or the datetime object for method chaining.
+
+
+Examples
+--------
+
+A php example::
+
+    // use \TYPO3\CMS\Core\Utility\GeneralUtility;
+    $stuff = GeneralUtility::makeInstance(
+        '\\Foo\\Bar\\Utility\\Stuff'
+    );
+    $stuff->do();
+
+Example in another language:
+
+..  code-block:: javascript
+    :linenos:
+    :emphasize-lines: 2-4
+
+    $(document).ready(
+        function () {
+            doStuff();
+        }
+    );
+
+A YAML example:
+
+..  code-block:: yaml
+
+    services:
+      Vendor\Extension\EventListener\YourListener:
+        tags:
+          - name: event.listener
+            identifier: 'your-self-choosen-identifier'
+            method: 'methodToConnectToEvent'
+            event: Vendor\MyExtension\Event\MyActionEvent

Documentation/Includes.rst.txt

@@ -0,0 +1,34 @@
+..  More information about this file:
+   https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
+
+..  ----------
+..  text roles
+..  ----------
+
+..  role:: aspect(emphasis)
+..  role:: bash(code)
+..  role:: html(code)
+..  role:: js(code)
+..  role:: php(code)
+..  role:: rst(code)
+..  role:: sep(strong)
+..  role:: sql(code)
+
+..  role:: tsconfig(code)
+    :class: typoscript
+
+..  role:: typoscript(code)
+..  role:: xml(code)
+    :class: html
+
+..  role:: yaml(code)
+
+..  default-role:: code
+
+..  ---------
+..  highlight
+..  ---------
+
+..  By default, code blocks use PHP syntax highlighting
+
+..  highlight:: php