README

Ein PHP-Paket für cookieloses Session-Handling mittels einmaliger Schlüssel (One-Time Keys).

Beschreibung

OTK (One-Time Key) ermöglicht ein sicheres, cookieloses Session-Management durch die Verwendung von einmaligen, zeitlich begrenzten Schlüsseln. Diese werden als URL-Parameter übergeben und können nur einmal verwendet werden. Die Keys werden in Redis gespeichert und nach einmaliger Verwendung automatisch gelöscht.

Hauptmerkmale

• Cookieloses Session-Handling: Ideal für Umgebungen, in denen Cookies nicht verwendet werden können oder sollen
• Einmalige Verwendung: Jeder Key kann nur einmal eingelöst werden
• Zeitliche Begrenzung: Keys verfallen automatisch nach einer konfigurierbaren Zeitspanne
• Redis-basiert: Schnelle und zuverlässige Speicherung
• Konfigurierbar: Anpassbare Key-Länge, Lebensdauer und Redis-Verbindung

Anforderungen

• PHP >= 7.4
• Redis-Server
• PHP Redis Extension
• tualo/ds ^1.5
• tualo/server ^1

Installation

composer require tualo/otk

Konfiguration

Die Konfiguration erfolgt über die Tualo Application Configuration:

// Redis-Verbindung
'otk' => [
    'redis_host' => '127.0.0.1',     // Redis Server Host
    'redis_port' => 6379,             // Redis Server Port
    'redis_db' => 1,                  // Redis Datenbank-Nummer
    
    // Key-Einstellungen
    'key_prefix' => 'otk',            // Präfix für Keys
    'key_length' => 36,               // Länge des Keys (in Zeichen)
    'key_lifetime' => 1442,           // Lebensdauer in Sekunden (~24 Min)
    
    // Session-Handling
    'use_for_session' => '1',         // '1' = OTK für Sessions verwenden
]

Verwendung

Grundlegende Verwendung

use Tualo\Office\OTK\OTK;

// OTK-Instanz abrufen
$otk = OTK::getInstance();

// Neuen Key generieren und Session-ID speichern
$key = $otk->setValue(); // Verwendet aktuelle Session-ID
// oder
$key = $otk->setValue('custom-session-id');

// Key in URL einbinden
$url = "https://example.com/page?" . $key;

// Bei nächster Anfrage: Session-ID aus Key auslesen
$sessionId = $otk->getValue();
if ($sessionId !== false) {
    session_id($sessionId);
    session_start();
}

CMS-Verwendung in Pug-Templates

Wenn die CMS-Middleware eingebunden ist, kann das OTK-Objekt direkt in Pug-Templates verwendet werden:

//- OTK-Key für aktuellen Benutzer/Session generieren
- var otkKey = cms.otk().setValue()

//- Link mit OTK generieren
a(href=`/secure-page?${otkKey}`) Sicherer Link

//- Oder mit JavaScript
script.
  var key = '#{cms.otk.setValue()}';
  var url = `/api/endpoint?${key}`;
  fetch(url).then(res => res.json());

//- Beispiel: Download-Link mit zeitlich begrenztem Zugriff
button(onclick=`window.location='/download/file.pdf?${cms.otk.setValue()}'`) 
  | Datei herunterladen

PHP-Seite (CMS-Middleware aktivieren):

use Tualo\Office\OTK\CMSMiddleware\OTKCMSMiddleware;

// Middleware registrieren
OTKCMSMiddleware::register();

Nach der Registrierung steht cms.otk in allen Pug-Templates zur Verfügung und bietet dieselben Methoden wie die OTK-Klasse.

Automatisches Session-Handling

Das Middleware-System ermöglicht automatisches Session-Handling:

use Tualo\Office\OTK\Middleware\OTKSession;

// Middleware registrieren
OTKSession::register();

Die Middleware:

1. Prüft ob use_for_session aktiviert ist
2. Sucht nach OTK-Keys in der Anfrage
3. Extrahiert die Session-ID aus dem Key
4. Startet die Session automatisch
5. Löscht den verwendeten Key

Key-Format

Keys werden automatisch nach folgendem Schema generiert:

{prefix}_{random_hex_string}

Beispiel:

otk_a7b3c9d1e5f2a4b6c8d0e1f3a5b7c9d1e3f5

Manuelle Key-Verwaltung

$otk = OTK::getInstance();

// Key generieren
$key = $otk->setValue('my-session-id');
echo "Ihr Key: " . $key;

// Key auflösen (nur einmal möglich!)
$sessionId = $otk->getValue();
if ($sessionId !== false) {
    echo "Session-ID: " . $sessionId;
} else {
    echo "Key ungültig oder bereits verwendet";
}

Anwendungsfälle

1. E-Mail-Links

// Link für E-Mail generieren
$otk = OTK::getInstance();
$key = $otk->setValue($userId);
$link = "https://example.com/login?" . $key;

// E-Mail versenden mit $link

2. API-Tokens

// Temporären Zugangstoken erstellen
$otk = OTK::getInstance();
$token = $otk->setValue($apiSessionData);

// Token an Client zurückgeben
return ['access_token' => $token];

3. Cookie-freie Mobile Apps

// Bei Login: Key generieren
$key = $otk->setValue($sessionId);

// Key an App zurückgeben
return ['otk' => $key];

// App sendet Key bei nächster Anfrage als URL-Parameter
// Middleware löst automatisch Session auf

Sicherheitshinweise

• Einmalige Verwendung: Keys werden nach Verwendung automatisch gelöscht
• Zeitliche Begrenzung: Keys verfallen nach der konfigurierten Lebensdauer
• HTTPS verwenden: Keys in URLs sollten nur über verschlüsselte Verbindungen übertragen werden
• Key-Länge: Standard 36 Zeichen bieten ausreichende Entropie gegen Brute-Force
• Logging: Keys sollten nicht in Logs gespeichert werden

Fehlerbehandlung

try {
    $otk = OTK::getInstance();
    $sessionId = $otk->getValue();
    
    if ($sessionId === false) {
        // Key nicht gefunden oder bereits verwendet
        throw new Exception('Ungültiger oder abgelaufener Key');
    }
    
    session_id($sessionId);
    session_start();
    
} catch (Exception $e) {
    // Redis-Verbindungsfehler oder andere Probleme
    error_log($e->getMessage());
}

Lizenz

MIT

Autor

Thomas Hoffmann
thomas.hoffmann@tualo.de

Support

Bei Fragen oder Problemen erstellen Sie bitte ein Issue im Repository.