Manual.rst: Describe REST authentication

extension/Documentation/Manual.rst

@@ -433,6 +433,8 @@ Extension Manager: QFQ Configuration
 | securityGetMaxLength              | 50                                                    | GET vars longer than 'x' chars triggers an `attack-recognized`.            |
 |                                   |                                                       | `ExceptionMaxLength`_.                                                     |
 +-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
+| securityFailedAuthDelay           | 3                                                     | If authorization fails, sleep 'x' seconds before answering the request.    |
++-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
 | Form-Config                                                                                                                                                            |
 +-----------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------+
 | recordLockTimeoutSeconds          | 900                                                   | Timeout for record locking. After this time, a record will be replaced.    |
@@ -1685,7 +1687,9 @@ Store: *CLIENT* - C
  +=========================+==========================================================================================================================================+
  | s                       | =SIP                                                                                                                                     |
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
- | r                       | record id. Typically stored in SIP, rarely specified on the URL                                                                          |
+ | r                       | record id. Only if specified as GET parameter - typically stored in SIP (=STORE_SIP)                                                     |
+ +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
+ | form                    | Name of form to load. Only if specified as GET parameter - typically stored in SIP (=STORE_SIP)                                          |
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
  | HTTP_HOST               | current HTTP HOST                                                                                                                        |
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
@@ -1693,7 +1697,7 @@ Store: *CLIENT* - C
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
  | '$_SERVER[*]'           | All other variables accessible by *$_SERVER[]*. Only the often used have a pre-defined sanitize class.                                   |
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
- | form                    | Unique name of current form                                                                                                              |
+ | Authorization           | Value of the HTTP Header 'Authorization'. This is typically not set. Mostly used for authentication of REST requests                     |
  +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
 
 .. _STORE_TYPO3:
@@ -7638,7 +7642,8 @@ A REST (GET) form has two modes: ::
   a) data: specific content to a given id. Defined via 'form.parameter.restSqlData'. This mode is selected
      if there is an id>0 given.
 
-  b) list: a list of records will be exported. Defined via 'form.parameter.restSqlList'. This mode is selected if there is no id or id=0.
+  b) list: a list of records will be exported. Defined via 'form.parameter.restSqlList'. This mode is selected if there
+     is no id or id=0.
 
 There are  *no* FormElements.
 
@@ -7668,19 +7673,60 @@ Form.parameter:
 | Attribute         | Description                                                                  |
 +===================+==============================================================================+
 | restSqlData       | SQL query selects content shown in data mode.                                |
-|                   | restSqlData={{!SELECT id, name, gender FROM Person WHERE id={{r:T0}} }}      |
+|                   | restSqlData={{!SELECT id, name, gender FROM Person WHERE id='{{r:T0}}'' }}   |
 +-------------------+------------------------------------------------------------------------------+
 | restSqlList       | SQL query selects content shown in data mode.                                |
 |                   | restSqlData={{!SELECT id, name FROM Person }}                                |
 +-------------------+------------------------------------------------------------------------------+
-| restParam         | CSV list of variable names.                                                  |
-|                   | restParam=pId,adrId                                                          |
+| restParam         | Optional. CSV list of variable names. E.g.: restParam=pId,adrId              |
++-------------------+------------------------------------------------------------------------------+
+| restToken         | Optional. User defined string. For dynamic token see below.                  |
 +-------------------+------------------------------------------------------------------------------+
 
-There are no `special-column-names`_ available in 'restSqlData' or 'restSqlList'. Especially there are no
-SIPs possible, cause REST typically does not offer sessions/cookies which are needed for SIPs.
 
-Autorizatioin
+There are no `special-column-names`_ available in 'restSqlData' or 'restSqlList'. Also there are no
+SIPs possible, cause REST typically does not offer sessions/cookies (which are necessary for SIPs).
+
+Authorization
+^^^^^^^^^^^^^
+
+By default, the REST API is public accessible.
+
+If this is not wished, HTTP AUTH might be used (configured via webserver) or the
+QFQ internal 'HTTP header token based authorization'.
+
+Token based authorization
+'''''''''''''''''''''''''
+
+A form will require a 'token based authorization', as soon as there is a 'form.parameter.restToken' defined.
+Therefore the HTTP Header 'Authorization' has to be set with 'token=<secret token>'. The 'secret token' will
+be checked against the server. Using HTTPS, such token can't be sniffed and will typically not be logged in
+any server logs.
+
+Example: ::
+
+  form.parameter.restToken=myCrypticString0123456789
+
+  Test via commandline: curl -X GET -H 'Authorization: Token token=myCrypticString0123456789' "http://localhost/qfq/typo3conf/ext/qfq/Source/api/rest.php/person/123/address/"
+
+The static setup with 'form.parameter.restToken=myCrypticString0123456789' is fine, as long as only one token
+exist. In case of multiple tokens, replace the static string against a SQL query.
+
+General: The HTML Header Authorization token is available in STORE_CLIENT via '{{Authorization:C:alnumx}}'.
+
+For example all created tokens are saved in a table 'Auth' with a column 'token'. Define: ::
+
+  form.parameter.restToken={{SELECT a.token FROM Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' }}
+
+To restrict access to a subset of data, just save the limitations inside the Auth record and update the query
+to check it: ::
+
+  form.parameter.restToken={{SELECT a.token FROM Auth AS a WHERE a.token='{{Authorization:C:alnumx}}'}}
+  form.parameter.restSqlList={{!SELECT p.id, p.name, p.email FROM Person AS p, Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' AND a.attribute=p.attribute}}
+  form.parameter.restSqlData={{!SELECT p.* FROM Person AS p, Auth AS a WHERE a.token='{{Authorization:C:alnumx}}' AND a.attribute=p.attribute AND p.id='{{r:T0}}' }}
+
+If authorization is denied, the request will be answered with a delay of 3 seconds (configured via securityFailedAuthDelay).
+
 
 .. _applicationTest:
 
@@ -7689,7 +7735,7 @@ Application Test
 
 With a framework like https://www.seleniumhq.org/ it's possible to play and verify unattended  test cases.
 
-To assist such frameworks and to make the tests reliable, an individual tag might be assigned to elements which have to
+To assist such frameworks and to make the tests reliable, an individual tag might be assigned to HTML elements which have to
 interact with the test framework.
 
 Form