Add Token authentication.

Author: robol

API.md

@@ -4,6 +4,22 @@ Sono attualmente in sviluppo delle API REST per CAPS, che vengono usate
 da (buona parte) del codice Javascript e in particolare la parte di 
 interfaccia utente sviluppata in React. 
 
+## Autenticazione amministrativa con token
+
+Se l'istanza configura `CAPS_ADMIN_TOKEN` e `CAPS_ADMIN_TOKEN_USER`, tutte le
+API possono essere invocate con privilegi amministrativi passando il token
+nell'header HTTP `Authorization`:
+
+```http
+Authorization: Bearer <CAPS_ADMIN_TOKEN>
+```
+
+`CAPS_ADMIN_TOKEN_USER` deve essere lo username di un utente già presente nel
+database. L'utente viene usato per attribuire operazioni, log e record creati;
+i privilegi amministrativi sono applicati soltanto alla richiesta autenticata
+dal token. Il token non viene accettato nella query string e deve essere usato
+esclusivamente tramite HTTPS.
+
 ## Metodi disponibili
 
 I Controller sono in `backend/src/Controller/Api/v1/` e i vari endpoint supportano i metodi HTTP GET, POST, PATCH e DELETE. 

backend/config/app.php

@@ -60,6 +60,13 @@
         'readonly' => env('CAPS_READONLY', '')
     ],
 
+    // Optional instance-wide Bearer token. Both values must be set to enable it.
+    // The username must identify an existing user, used for ownership and logs.
+    'AdminToken' => [
+        'token' => env('CAPS_ADMIN_TOKEN', ''),
+        'username' => env('CAPS_ADMIN_TOKEN_USER', ''),
+    ],
+
     'UnipiAuthenticate' => [
       'microsoft_oauth2_appid' => '',
       'microsoft_oauth2_client_secret' => '',

backend/example.env

@@ -32,6 +32,11 @@ CAPS_CDS='Testing'
 # default:
 # READONLY=''
 
+# Optional administrator Bearer token. Both variables are required and the
+# configured user must already exist in CAPS.
+# CAPS_ADMIN_TOKEN='replace-with-a-long-random-token'
+# CAPS_ADMIN_TOKEN_USER='admin'
+
 # Connection information used by the ORM to connect
 # to your application's datastores.
 #
@@ -104,4 +109,3 @@ CAPS_CDS='Testing'
 # for more information.
 #
 # MAIL_FROM='you@localhost'
-

backend/src/Application.php

@@ -22,6 +22,7 @@
  */
 namespace App;
 
+use App\Authentication\Authenticator\AdminTokenAuthenticator;
 use App\Identifier\Resolver\UnipiResolver;
 use Authentication\AuthenticationService;
 use Authentication\AuthenticationServiceInterface;
@@ -109,8 +110,12 @@ public function middleware($middlewareQueue): \Cake\Http\MiddlewareQueue
                 'cacheTime' => Configure::read('Asset.cacheTime')
             ]))
 
-            // Add CSRF protection
-            ->add(new SessionCsrfProtectionMiddleware())
+            // Add CSRF protection. Stateless Bearer-token requests are exempt.
+            ->add((new SessionCsrfProtectionMiddleware())->skipCheckCallback(
+                function (ServerRequestInterface $request): bool {
+                    return AdminTokenAuthenticator::matchesRequest($request);
+                }
+            ))
 
             // Add routing middleware.
             // If you have a large number of routes connected, turning on routes
@@ -160,7 +165,10 @@ public function getAuthenticationService(ServerRequestInterface $request) : Auth
             IdentifierInterface::CREDENTIAL_PASSWORD => 'password'
         ];
 
-        // Load the authenticators. Session should be first.
+        // The administrator token takes precedence over an existing session.
+        $service->loadAuthenticator(AdminTokenAuthenticator::class);
+
+        // Load the remaining authenticators.
         $service->loadAuthenticator('Authentication.Session');
         $service->loadAuthenticator('Authentication.Form', [
             'fields' => $fields,

docker/app.php

@@ -34,6 +34,11 @@
         'readonly' => ('@CAPS_READONLY@' == '') ? false : '@CAPS_READONLY@'
     ],
 
+    'AdminToken' => [
+        'token' => env('CAPS_ADMIN_TOKEN', ''),
+        'username' => env('CAPS_ADMIN_TOKEN_USER', ''),
+    ],
+
     'UnipiAuthenticate' => [
       'microsoft_oauth2_appid' => '@MICROSOFT_OAUTH2_APPID@',
       'microsoft_oauth2_client_secret' => '@MICROSOFT_OAUTH2_CLIENT_SECRET@',

docker/caps.env.template

@@ -47,6 +47,12 @@ CAPS_CDS=Matematica
 # string, that will be displayed to the user. 
 # CAPS_READONLY=Read-only mode enabled
 
+# Optional administrator Bearer token. Both variables are required and the
+# configured user must already exist in CAPS. Generate a token with:
+# openssl rand -hex 32
+# CAPS_ADMIN_TOKEN=replace-with-a-long-random-token
+# CAPS_ADMIN_TOKEN_USER=admin
+
 # Username for the mysql user for CAPS. Should match CAPS_DB_USERNAME
 # if using the combined docker-compose setup
 MYSQL_USER=caps
@@ -77,4 +83,3 @@ OAUTH2_CLIENT_SECRET=
 OAUTH2_URL_AUTHORIZE=https://iam.unipi.it/oauth2/authorize
 OAUTH2_URL_TOKEN=https://iam.unipi.it/oauth2/token
 OAUTH2_URL_USERINFO=https://iam.unipi.it/oauth2/userinfo
-

docker/docker-compose-dev.yml

@@ -16,6 +16,7 @@ services:
       - "../backend/src:/backend/src:ro"
       - "../backend/templates:/backend/templates:ro"
       - "../backend/webroot:/backend/webroot:ro"
+      - "../backend/config/app.php:/backend/config/app.php:ro"
       - "../backend/config/Migrations:/backend/config/Migrations"
       - "../backend/config/routes.php:/backend/config/routes.php"
       - "./logs:/backend/logs"

example.env

@@ -51,6 +51,11 @@ CAPS_USERS_PASSWD="admin:admin,user:user"
 # CAPS_ADMIN=''
 CAPS_ADMINS='admin'
 
+# Optional administrator Bearer token. The user must already exist in CAPS.
+# Generate a token with: openssl rand -hex 32
+# CAPS_ADMIN_TOKEN='replace-with-a-long-random-token'
+# CAPS_ADMIN_TOKEN_USER='admin'
+
 # Connection information used by the ORM to connect
 # to your application's datastores.
 #
@@ -124,4 +129,3 @@ CAPS_DB_DATABASE=caps.sqlite
 # for more information.
 #
 # MAIL_FROM=you@localhost
-