Hagen-ID

PWA-Ausweisansicht auf einem Smartphone: Schulname, Foto, Name, Klasse, dynamischer QR-Code und Gültigkeit

Der digitale Ausweis in der PWA — mit Testdaten und dynamischem QR-CodeThe digital ID card in the PWA — with test data and a dynamic QR code

InhaltsverzeichnisTable of Contents

Was ist Hagen-ID?What is Hagen-ID?
Funktionsweise im ÜberblickHow it Works
Fälschungsschutz: TOTP & digitale SignaturTamper Protection: TOTP & Digital Signature
Datenschutz & DSGVO-KonformitätPrivacy & GDPR Compliance
Gespeicherte Daten & DatenminimierungStored Data & Data Minimization
Rollenkonzept & ZugriffssteuerungRole Model & Access Control
VerwaltungsprozesseAdministrative Processes
Technische ArchitekturTechnical Architecture
Einrichtung & BetriebSetup & Operations
Kontakt & nächste SchritteContact & Next Steps

Hagen-ID ist ein digitaler Schülerausweis, der als Progressive Web App (PWA) auf dem Smartphone der Schülerinnen und Schüler läuft. Er ersetzt den klassischen Papier- oder Plastikausweis durch eine fälschungssichere, digital verifizierbare Lösung.Hagen-ID is a digital student ID card that runs as a Progressive Web App (PWA) on students' smartphones. It replaces traditional paper or plastic ID cards with a tamper-proof, digitally verifiable solution.

Das System wurde speziell für den Schulkontext in Nordrhein-Westfalen entwickelt und berücksichtigt die Anforderungen der DSGVO sowie der schulrechtlichen Datenschutzverordnung (VO-DV I / VO-DV II).The system was specifically developed for the school context in North Rhine-Westphalia and meets the requirements of the GDPR as well as state school data protection regulations (VO-DV I / VO-DV II).

KernmerkmaleKey Features

Kein App-Download nötig:No app download required: Hagen-ID ist eine Progressive Web App (PWA) und läuft direkt im Browser. Schülerinnen und Schüler können die Anwendung optional zum Homescreen hinzufügen, sodass sie sich wie eine native App verhält — ohne App Store, ohne Installation, auf jedem Gerät mit einem modernen Browser nutzbar.Hagen-ID is a Progressive Web App (PWA) and runs directly in the browser. Students can optionally add the app to their home screen, making it behave like a native app — no app store, no installation, usable on any device with a modern browser.
Fälschungssicherer QR-Code:Tamper-proof QR code: Der QR-Code auf dem Ausweis wechselt alle 30 Sekunden und ist kryptografisch signiert. Ein Screenshot oder eine Kopie ist daher wertlos.The QR code on the ID card changes every 30 seconds and is cryptographically signed. A screenshot or copy is therefore worthless.
Offline-fähig:Works offline: Nach dem erstmaligen Login funktioniert der Ausweis auch ohne Internetverbindung. Die QR-Code-Generierung erfolgt vollständig auf dem Gerät.After the initial login, the ID card works without internet connectivity. QR code generation happens entirely on the device.
Ein-Geräte-Prinzip (Highlander):Single-device principle (Highlander): Der Ausweis ist immer nur auf genau einem Gerät gültig. Ein Login auf einem neuen Gerät macht den alten Ausweis automatisch ungültig.The ID card is always valid on exactly one device. Login on a new device automatically invalidates the old card.
Auch für Lehrkräfte:Also for teachers: Lehrkräfte erhalten ebenfalls einen digitalen Ausweis über die PWA. Sie werden in einer virtuellen Klasse „Lehrerkollegium“ geführt und können ihr Foto selbst über die App hochladen.Teachers also receive a digital ID card via the PWA. They are managed in a virtual class "Lehrerkollegium" (staff) and can upload their own photo directly through the app.
Zentrale Verwaltung:Central management: Schulverwaltungen pflegen Schülerdaten über ein Admin-Dashboard im Browser — inklusive CSV-Import aus der Schulverwaltungssoftware oder automatisierter Synchronisation über eine REST-API.Schools manage student data through a browser-based admin dashboard — including CSV import from student management software or automated synchronization via a REST API.
Schulbescheinigung als PDF:Enrollment certificate as PDF: Auf Wunsch können Schülerinnen und Schüler eine Schulbescheinigung direkt aus der App herunterladen — mit einem dauerhaften Verifizierungs-QR-Code, der beim Scannen den aktuellen Einschreibestatus live anzeigt.Optionally, students can download an enrollment certificate directly from the app — with a permanent verification QR code that shows the current enrollment status live when scanned.

Hagen-ID besteht aus drei Komponenten: dem Schülerausweis (PWA) auf dem Smartphone, dem Admin-Dashboard für die Schulverwaltung und der Verifizierungsschnittstelle zum Prüfen eines vorgelegten Ausweises.Hagen-ID consists of three components: the student ID card (PWA) on the smartphone, the admin dashboard for school management, and the verification interface for checking a presented ID.

Der Ausweis auf dem SmartphoneThe ID Card on the Smartphone

Schülerinnen und Schüler rufen die PWA im Browser auf und melden sich mit ihrem Nachnamen, Geburtsdatum und einer persönlichen 6-stelligen PIN an. Nach dem Login wird der digitale Ausweis angezeigt: Name, Klasse, Schulfoto und ein dynamischer QR-Code, der alle 30 Sekunden wechselt.Students open the PWA in their browser and log in with their last name, date of birth, and a personal 6-digit PIN. After login, the digital ID is displayed: name, class, school photo, and a dynamic QR code that changes every 30 seconds.

Login-Bildschirm der PWA: Nachname, Geburtsdatum und 6-stellige PIN

Login mit Nachname, Geburtsdatum und PIN — ohne Passwort, ohne E-Mail-AdresseLogin with last name, date of birth and PIN — no password, no email address

Verifizierung des AusweisesID Card Verification

Wer die Identität prüfen möchte — zum Beispiel an der Bibliothek, in der Mensa oder am Schuleingang — scannt den QR-Code mit einem beliebigen Smartphone oder Tablet. Die Verifizierung erfolgt serverseitig und liefert ein eindeutiges Ergebnis: gültig oder ungültig.Anyone who wants to verify identity — for example at the library, in the cafeteria, or at the school entrance — scans the QR code with any smartphone or tablet. Verification happens on the server side and returns a clear result: valid or invalid.

Kein spezielles Gerät nötig:No special device needed: Die Verifizierung funktioniert mit jedem Gerät, das einen QR-Code scannen kann. Es wird keine spezielle App benötigt — ein Smartphone-Browser genügt.Verification works with any device that can scan a QR code. No special app is needed — a smartphone browser is sufficient.

Ablauf im ÜberblickProcess Overview

Schülerdaten importierenImport student data → Login-PINs verteilenDistribute login PINs → Schüler loggt sich einStudent logs in → Ausweis aktivID card active → QR-Code verifizierbarQR code verifiable

Der Fälschungsschutz von Hagen-ID basiert auf zwei kryptografischen Verfahren, die ineinandergreifen: TOTP (Time-based One-Time Password) für den zeitlich begrenzten Code und eine gerätegebundene digitale Signatur (ECDSA P-256) über den gesamten QR-Code-Inhalt.Hagen-ID's tamper protection is based on two cryptographic methods that work together: TOTP (Time-based One-Time Password) for the time-limited code and a device-bound digital signature (ECDSA P-256) over the entire QR code content.

TOTP — der wechselnde CodeTOTP — the changing code Cryptography

Bei der Erstanmeldung erhält jeder Schüler ein individuelles TOTP-Secret (eine zufällige Zeichenfolge nach RFC 6238). Aus diesem Secret und der aktuellen Uhrzeit berechnet die PWA alle 30 Sekunden einen neuen 6-stelligen Code — vollständig offline auf dem Gerät. Der Server kennt dasselbe Secret und kann den Code unabhängig verifizieren.At first login, each student receives an individual TOTP Secret (a random string according to RFC 6238). Using this secret and the current time, the PWA calculates a new 6-digit code every 30 seconds — entirely offline on the device. The server knows the same secret and can verify the code independently.

Das bedeutet: Selbst wenn jemand den QR-Code fotografiert oder abschreibt, ist dieser nach spätestens 30 Sekunden ungültig. Ein statischer Screenshot reicht nicht aus, um sich als eine andere Person auszugeben.This means: even if someone photographs or writes down the QR code, it becomes invalid after at most 30 seconds. A static screenshot is not sufficient to impersonate another person.

Gerätegebundene Signatur — der digitale StempelDevice-bound Signature — the digital seal Cryptography

Zusätzlich zum TOTP-Code wird der gesamte QR-Code-Inhalt (Schüler-ID, TOTP-Code, Session-Kennung und Zeitstempel) digital signiert — mit ECDSA auf der Kurve P-256, einem etablierten asymmetrischen Signaturverfahren, das jeder moderne Browser nativ unterstützt.In addition to the TOTP code, the entire QR code content (student ID, TOTP code, session identifier and timestamp) is digitally signed — using ECDSA on the P-256 curve, an established asymmetric signature algorithm natively supported by every modern browser.

Das Schlüsselpaar entsteht dabei direkt auf dem Gerät des Schülers — über die WebCrypto-API des Browsers und als nicht exportierbarer Schlüssel: Der private Schlüssel kann per Konstruktion nicht ausgelesen werden, auch nicht durch eingeschleuste Schadskripte, und verlässt das Gerät nie. Nur der öffentliche Schlüssel wird beim Server registriert und dient dort ausschließlich zur Verifizierung — der Server selbst signiert nie.The key pair is created directly on the student's device — via the browser's WebCrypto API and as a non-extractable key: by construction, the private key cannot be read out, not even by injected malicious scripts, and never leaves the device. Only the public key is registered with the server, where it is used solely for verification — the server itself never signs.

Zusammenspiel:How it works together: Der QR-Code enthält die Schüler-ID, den aktuellen TOTP-Code, eine Session-Kennung, den Zeitstempel und die digitale Signatur über all diese Daten. Bei der Verifizierung prüft der Server:The QR code contains the student ID, the current TOTP code, a session identifier, the timestamp and the digital signature over all this data. When verifying, the server checks:

1. Ist der TOTP-Code für diesen Schüler gerade gültig? (Zeitfenster: ±30 Sekunden)1. Is the TOTP code currently valid for this student? (Time window: ±30 seconds)

2. Ist der Zeitstempel aktuell?2. Is the timestamp fresh?

3. Gehört die Session-Kennung zur aktuell aktiven Sitzung? (Ein-Geräte-Prinzip)3. Does the session identifier belong to the currently active session? (single-device principle)

4. Stimmt die Signatur mit dem registrierten Geräteschlüssel überein?4. Does the signature match the registered device key?

Erst wenn alle vier Prüfungen bestanden sind, gilt der Ausweis als verifiziert. Ein QR-Code ohne gültige Signatur wird grundsätzlich abgelehnt (fail-closed).The ID card is only considered verified if all four checks pass. A QR code without a valid signature is always rejected (fail-closed).

Verification flow: QR code scan to result — TOTP check, signature check, session check

Highlander-Prinzip — ein Gerät, ein AusweisHighlander Principle — one device, one ID card Auth

Bei jedem Login wird ein neuer kryptografischer Session-Token generiert (256 Bit Entropie). Der SHA-256-Hash dieses Tokens wird in der Datenbank gespeichert. Gleichzeitig wird der bisherige Geräteschlüssel serverseitig entwertet; das neue Gerät erzeugt ein frisches Schlüsselpaar und registriert dessen öffentlichen Schlüssel. Dadurch werden alle vorherigen Sitzungen automatisch ungültig.At each login, a new cryptographic session token is generated (256 bits of entropy). The SHA-256 hash of this token is stored in the database. At the same time, the previous device key is invalidated on the server; the new device generates a fresh key pair and registers its public key. This automatically invalidates all previous sessions.

Konsequenz:Consequence: Selbst wenn jemand die Login-Daten eines Schülers kennt und sich auf einem zweiten Gerät anmeldet, wird das erste Gerät sofort abgemeldet und der dort gespeicherte private Schlüssel ist wertlos. Es kann zu keinem Zeitpunkt zwei gültige Ausweise für dieselbe Person geben.Even if someone knows a student's login credentials and logs in on a second device, the first device is immediately logged out and the private key stored there becomes worthless. There can never be two valid ID cards for the same person at any time.

DatenminimierungData Minimization

Hagen-ID speichert ausschließlich die Daten, die für die Funktion eines Schülerausweises zwingend erforderlich sind: Vor- und Nachname, Geburtsdatum, Klassenzugehörigkeit, Schulfoto und eine interne Schüler-ID aus der Schulverwaltungssoftware. Optional kann eine E-Mail-Adresse hinterlegt werden (z. B. für einen künftigen PIN-Reset). Es werden keine Leistungsdaten, Noten, Fehlzeiten, Adressen oder sonstigen personenbezogenen Daten erhoben.Hagen-ID stores only data that is strictly required for the function of a student ID: first and last name, date of birth, class membership, school photo, and an internal student ID from the school management software. Optionally, an email address can be stored (e.g., for future PIN reset). No performance data, grades, attendance records, addresses or other personal data are collected.

Kein Tracking, keine AnalyseNo Tracking, No Analytics

Die PWA enthält weder Analytics-Tools noch Tracking-Pixel oder Drittanbieter-Skripte. Es werden keine Nutzungsprofile erstellt. Die Ausweis-App kommuniziert ausschließlich mit dem schuleigenen Server — zu keinem Zeitpunkt werden Daten an externe Dienste übertragen.The PWA contains neither analytics tools nor tracking pixels or third-party scripts. No usage profiles are created. The ID card app communicates exclusively with the school's own server — data is never transmitted to external services at any time.

Verschlüsselung in der DatenbankEncryption in the Database

Besonders sensible Felder werden in der Datenbank zusätzlich verschlüsselt gespeichert (Fernet: AES + HMAC): Vor- und Nachname, Geburtsdatum, Schulfoto, Login-PIN und TOTP-Secret. Der Schlüssel dafür liegt außerhalb der Datenbank in der Server-Konfiguration. Ein entwendetes Datenbank-Backup enthält damit keine lesbaren Schülerdaten. Der Login-Abgleich erfolgt über sogenannte Blind-Indexe (HMAC), sodass die Klartextdaten dafür nicht benötigt werden.Particularly sensitive fields are additionally stored encrypted in the database (Fernet: AES + HMAC): first and last name, date of birth, school photo, login PIN and TOTP secret. The key is kept outside the database in the server configuration. A stolen database backup therefore contains no readable student data. Login matching is done via blind indexes (HMAC), so the plaintext data is not needed for it.

Speicherung und LöschungStorage and Deletion

Soft-Delete mit Löschfrist:Soft-delete with retention period: Wenn ein Schüler aus dem System entfernt wird (z. B. durch einen aktualisierten CSV-Import), werden die Daten zunächst als gelöscht markiert, aber nicht sofort entfernt. Nach einer Frist von 4 Wochen erfolgt die endgültige, unwiderrufliche Löschung durch einen automatischen Bereinigungsprozess. In diesem Zeitraum kann eine versehentliche Löschung rückgängig gemacht werden.When a student is removed from the system (e.g., through an updated CSV import), the data is first marked as deleted but not immediately removed. After a 4-week retention period, permanent, irreversible deletion occurs through an automated cleanup process. Accidental deletions can be recovered during this period.
Passwörter:Passwords: Admin-Passwörter werden ausschließlich als bcrypt-Hash gespeichert — ein Brute-Force-resistentes Verfahren mit automatischem Salt. Klartext-Passwörter werden zu keinem Zeitpunkt in der Datenbank abgelegt.Admin passwords are stored exclusively as bcrypt hashes — a brute-force resistant algorithm with automatic salt. Plain text passwords are never stored in the database.
Session-Tokens:Session tokens: Auch Session-Tokens werden nicht im Klartext gespeichert. In der Datenbank liegt nur der SHA-256-Hash. Bei einem hypothetischen Datenbank-Leak können daraus keine gültigen Sitzungen rekonstruiert werden.Session tokens are also not stored in plain text. Only the SHA-256 hash is stored in the database. In a hypothetical database leak, no valid sessions can be reconstructed from them.

Verifizierung ohne DatenpreisgabeVerification Without Data Disclosure

Wenn ein Ausweis per QR-Code gescannt wird, sendet der Prüfende lediglich den Inhalt des QR-Codes an den Server. Der Server antwortet mit einem binären Ergebnis: gültig oder ungültig, ergänzt um den Namen und das Foto des Schülers (damit die prüfende Person das Gesicht abgleichen kann). Es werden keine darüber hinausgehenden Daten übertragen.When an ID card is scanned via QR code, the verifier only sends the content of the QR code to the server. The server responds with a binary result: valid or invalid, supplemented with the student's name and photo (so the verifier can check the face). No additional data is transmitted.

Audit-Log — sparsam, pseudonym, befristetAudit Log — minimal, pseudonymous, time-limited

Sicherheitsrelevante Ereignisse werden in einem Änderungsprotokoll (Audit-Log) festgehalten: CSV-Imports, manuelle Löschungen und Deaktivierungen, fehlgeschlagene Login-Versuche, Ausweis-Verifizierungen sowie die Vergabe und der Widerruf von API-Schlüsseln. Das Protokoll ist pseudonym (IDs statt Klarnamen), wird nach 180 Tagen automatisch bereinigt und ist ausschließlich für den Systembetreiber einsehbar.Security-relevant events are recorded in a change log (audit log): CSV imports, manual deletions and deactivations, failed login attempts, ID verifications, and the issuing and revocation of API keys. The log is pseudonymous (IDs instead of names), automatically purged after 180 days, and visible only to the system operator.

Bewusst nicht protokolliert wird der normale Abruf des eigenen Ausweises durch die Schülerin oder den Schüler. Nur für einen konkreten Verdachtsfall (z. B. Missbrauch eines Ausweises) kann der Betreiber eine gezielte, zeitlich begrenzte Detail-Nachverfolgung aktivieren — auf eine Schule oder eine einzelne ID eingegrenzt, mit automatischer Abschaltung (Standard 48 Stunden, maximal 7 Tage). Die Aktivierung selbst wird ebenfalls protokolliert.Routine access to one's own ID card by the student is deliberately not logged. Only for a concrete suspicious case (e.g., misuse of an ID) can the operator activate a targeted, time-limited detailed trace — scoped to one school or a single ID, with automatic shutoff (default 48 hours, maximum 7 days). The activation itself is also logged.

Rechtsgrundlage:Legal basis: Die Verarbeitung der Daten stützt sich auf die Erfüllung der schulischen Aufgabe (Art. 6 Abs. 1 lit. e DSGVO) in Verbindung mit den schulrechtlichen Datenschutzverordnungen des Landes NRW. Für das Schülerfoto kann eine Einwilligung erforderlich sein, sofern es über den Zweck der Identifikation hinaus verwendet wird.Data processing is based on the fulfillment of school tasks (Art. 6 Para. 1 lit. e GDPR) in connection with state school data protection regulations in NRW. Consent may be required for student photos if used beyond the purpose of identification.

Die folgende Tabelle zeigt alle gespeicherten Datenkategorien, ihren Zweck und den Speicherort.The following table shows all stored data categories, their purpose, and storage location.

DatenkategorieData Category	ZweckPurpose	SpeicherortStorage Location
Vor- und NachnameFirst and Last Name	Anzeige auf dem Ausweis, Login-IdentifikationDisplay on ID card, login identification	Datenbank (Server, verschlüsselt)Database (Server, encrypted)
GeburtsdatumDate of Birth	Login-Authentifizierung, Anzeige auf AusweisLogin authentication, display on ID card	Datenbank (Server, verschlüsselt)Database (Server, encrypted)
KlassenzugehörigkeitClass Membership	Anzeige auf dem Ausweis, VerwaltungDisplay on ID card, administration	Datenbank (Server)Database (Server)
SchulfotoSchool Photo	Anzeige auf dem Ausweis, Identitätsprüfung bei VerifizierungDisplay on ID card, identity verification during verification	Datenbank (Server, verschlüsselt)Database (Server, encrypted)
Interne Schüler-IDInternal Student ID	Abgleich mit Schulverwaltungssoftware beim Import und SyncReconciliation with school management software during import and sync	Datenbank (Server)Database (Server)
E-Mail-Adresse (optional)Email Address (optional)	Optionales Feld, z. B. für künftigen PIN-ResetOptional field, e.g., for future PIN reset	Datenbank (Server)Database (Server)
6-stellige Login-PIN6-digit Login PIN	Authentifizierung der Schüler beim LoginStudent authentication during login	Datenbank (Server, verschlüsselt)Database (Server, encrypted)
TOTP-Secret	Generierung des wechselnden QR-CodesGeneration of changing QR code	Datenbank (Server, verschlüsselt) + Gerät (als nicht exportierbarer Schlüssel)Database (Server, encrypted) + Device (as non-extractable key)
Geräteschlüssel (privat)Device Key (private)	Signierung der QR-Codes (ECDSA P-256)Signing of QR codes (ECDSA P-256)	Nur auf dem Gerät des Schülers (nicht exportierbar)Only on student's device (non-extractable)
Geräteschlüssel (öffentlich)Device Key (public)	Serverseitige SignaturprüfungServer-side signature verification	Datenbank (Server)Database (Server)
Session-Token-Hash	Highlander-Prüfung (Ein-Geräte-Prinzip)Highlander check (single-device principle)	Datenbank (Server)Database (Server)

Was nicht gespeichert wird:What is not stored: Adressen, Telefonnummern, Noten, Fehlzeiten, Standortdaten, Geräteinformationen oder Nutzungsstatistiken. IP-Adressen werden beim normalen Abruf des eigenen Ausweises nicht gespeichert — nur bei sicherheitsrelevanten Ereignissen (z. B. fehlgeschlagenen Login-Versuchen) oder während einer aktiven Verdachtsfall-Nachverfolgung.Addresses, phone numbers, grades, attendance records, location data, device information or usage statistics. IP addresses are not stored during normal access to one's own ID — only for security-relevant events (e.g., failed login attempts) or during an active suspicious-case trace.

Daten auf dem SchülergerätData on Student Device

Auf dem Smartphone des Schülers werden nach dem Login folgende Daten lokal gespeichert: die Anmelde-Sitzung als HttpOnly-Cookies (per JavaScript nicht auslesbar, daher XSS-geschützt), das TOTP-Secret und der private Signierschlüssel — beide als nicht exportierbare kryptografische Schlüssel in der Browser-Datenbank (IndexedDB) — sowie die Ausweisdaten für die Offline-Anzeige. Diese Daten ermöglichen es, den Ausweis auch ohne Internetverbindung anzuzeigen und gültige QR-Codes zu erzeugen. Beim Abmelden werden sie gelöscht.The following data is stored locally on the student's smartphone after login: the login session as HttpOnly cookies (not readable by JavaScript, hence XSS-protected), the TOTP secret and the private signing key — both as non-extractable cryptographic keys in the browser database (IndexedDB) — plus the ID card data for offline display. This data allows the ID card to be displayed and valid QR codes to be generated even without internet connectivity. It is deleted on logout.

Hagen-ID unterscheidet drei Rollen im Admin-Bereich. Jede Rolle hat klar definierte Berechtigungen nach dem Prinzip der minimalen Rechte.Hagen-ID distinguishes three roles in the admin area. Each role has clearly defined permissions following the principle of least privilege.

SuperadminSuperadmin

Systemweiter Vollzugriff. Kann Schulen anlegen, alle Daten einsehen und systemübergreifende Einstellungen verwalten. Vorgesehen für den technischen Betreiber oder Schulträger.System-wide full access. Can create schools, view all data, and manage system-wide settings. Intended for technical operators or school authorities.

SchuladminSchool Admin

Vollzugriff auf die eigene Schule. Kann Schülerdaten importieren, Fotos hochladen, Klassen und Bildungsgänge verwalten, Login-PINs drucken und Schuleinstellungen anpassen. Vorgesehen für Schulleitungen und Sekretariate.Full access to their own school. Can import student data, upload photos, manage classes and programs, print login PINs, and adjust school settings. Intended for school principals and administrative staff.

LehrkraftTeacher

Eingeschränkter Lesezugriff auf die eigene Schule im Admin-Dashboard. Kann Schülerdaten einsehen, aber keine Imports durchführen und keine Daten verändern. Erhält zusätzlich einen eigenen digitalen Ausweis über die PWA (Klasse „Lehrerkollegium“) und kann das eigene Foto selbst über die App hochladen.Limited read-only access to their own school in the admin dashboard. Can view student data but cannot perform imports or modify data. Additionally receives their own digital ID via the PWA (class "Lehrerkollegium") and can upload their own photo directly through the app.

MandantenfähigkeitMulti-tenancy

Das System ist mandantenfähig: Mehrere Schulen können dieselbe Installation nutzen, ohne gegenseitig auf Daten zugreifen zu können. Jede Schule hat einen eigenen URL-Pfad (z. B. example.de/kkbk), eigenes Branding (Logo, Farben) und eigene Benutzerkonten. Schuladmins und Lehrkräfte sehen ausschließlich die Daten ihrer eigenen Schule.The system is multi-tenant: multiple schools can use the same installation without being able to access each other's data. Each school has its own URL path (e.g., example.com/kkbk), its own branding (logo, colors), and its own user accounts. School admins and teachers see only their own school's data.

Die Trennung wird nicht nur in der Anwendung geprüft, sondern zusätzlich auf Datenbankebene erzwungen (PostgreSQL Row-Level-Security): Selbst ein Programmierfehler in der Anwendung könnte die Daten einer anderen Schule nicht sichtbar machen — die Datenbank selbst verweigert den Zugriff.The separation is not only checked in the application but additionally enforced at the database level (PostgreSQL row-level security): even a programming error in the application could not expose another school's data — the database itself denies access.

Admin-AuthentifizierungAdmin Authentication

Administratoren melden sich mit E-Mail-Adresse und Passwort an. Das System setzt Rate Limiting ein: Nach 5 fehlgeschlagenen Anmeldeversuchen innerhalb von 15 Minuten wird temporär gesperrt — und zwar pro Konto und pro IP-Adresse, sodass sich die Sperre nicht durch wechselnde IP-Adressen umgehen lässt. Die Admin-Session wird über ein HttpOnly-Cookie verwaltet, das nicht per JavaScript ausgelesen werden kann und somit vor Cross-Site-Scripting (XSS) geschützt ist. Eine Passwortänderung macht alle bestehenden Sitzungen des Kontos sofort ungültig.Administrators log in with email address and password. The system implements rate limiting: after 5 failed login attempts within 15 minutes, access is temporarily blocked — per account and per IP address, so the lockout cannot be bypassed by rotating IP addresses. Admin sessions are managed via HttpOnly cookies, which cannot be read by JavaScript and are thus protected against Cross-Site Scripting (XSS) attacks. A password change immediately invalidates all existing sessions of the account.

7.1 Schülerdaten importieren (CSV-Import)7.1 Importing Student Data (CSV Import)

Das Sekretariat exportiert eine CSV-Datei aus der Schulverwaltungssoftware (z. B. SchILD-NRW) mit den Feldern: Interne ID, Vorname, Nachname, Geburtsdatum und Klasse. Diese Datei wird im Admin-Dashboard hochgeladen.The administrative office exports a CSV file from the school administration software (e.g., SchILD-NRW) with the fields: Internal ID, first name, last name, date of birth, and class. This file is uploaded in the admin dashboard.

Hagen-ID zeigt zunächst eine Vorschau aller Änderungen: Welche Schüler werden neu angelegt, welche aktualisiert, welche sind nicht mehr in der CSV enthalten (und werden daher zur Löschung vorgemerkt). Erst nach expliziter Bestätigung durch den Admin werden die Änderungen übernommen.Hagen-ID first shows a preview of all changes: which students will be created, which will be updated, and which are no longer in the CSV file (and will therefore be marked for deletion). Changes are only applied after explicit confirmation by the admin.

Admin-Dashboard: Schülerverwaltung mit Suchfeld, Klassen, Gültigkeit und Status (Testdaten)

Die Schülerverwaltung im Admin-Dashboard nach dem Import (Testdaten)Student management in the admin dashboard after import (test data)

Automatische TOTP-Secret-Generierung:Automatic TOTP Secret Generation: Für jeden neu angelegten Schüler wird automatisch ein individuelles TOTP-Secret erzeugt. Dies geschieht serverseitig mit einem kryptografisch sicheren Zufallsgenerator. Ebenso wird automatisch eine zufällige 6-stellige Login-PIN generiert.For each newly created student, an individual TOTP secret is automatically generated. This is done server-side using a cryptographically secure random number generator. A random 6-digit login PIN is also automatically generated.

Automatisierter Sync (Alternative zum CSV-Import):Automated Sync (Alternative to CSV Import): Für Schulen mit entsprechender IT-Infrastruktur bietet Hagen-ID auch eine REST-API zur automatisierten Synchronisation der Schülerdaten. Über diese API können externe Tools neue Schüler anlegen, bestehende Daten aktualisieren und ausgetretene Schüler deaktivieren — ohne manuellen CSV-Upload. Die Authentifizierung erfolgt über schulspezifische API-Keys. Mit SchildSpider steht ein fertiges Management-Tool fürs Sekretariat bereit, das den Abgleich mit SchILD-NRW übernimmt.For schools with suitable IT infrastructure, Hagen-ID also offers a REST API for automated synchronization of student data. Through this API, external tools can create new students, update existing data, and deactivate departed students — without manual CSV upload. Authentication is via school-specific API keys. With SchildSpider, a ready-made management tool for the school office is available that handles reconciliation with SchILD-NRW.

7.2 Login-PINs verteilen7.2 Distributing Login PINs

Nach dem Import können die Login-PINs über eine Druckfunktion im Admin-Dashboard als individuelle Kärtchen ausgedruckt werden. Jedes Kärtchen enthält den Namen des Schülers, die 6-stellige PIN und einen QR-Code, der direkt zur Login-Seite der Schule führt. Die Verteilung erfolgt über die Klassenlehrkräfte — analog zu Zugangsdaten für andere Schulsysteme.After import, login PINs can be printed as individual cards via a print function in the admin dashboard. Each card contains the student's name, the 6-digit PIN, and a QR code linking directly to the school's login page. Distribution is done through class teachers — similar to access credentials for other school systems.

Druckansicht der Login-PIN-Kärtchen: pro Person Name, Klasse, QR-Code und PIN (Testdaten)

Druckansicht der Login-PIN-Kärtchen — pro Person mit QR-Code zur Login-Seite (Testdaten)Print view of the login PIN cards — one per person with a QR code to the login page (test data)

7.3 Fotos hochladen7.3 Uploading Photos

Schülerfotos können im Admin-Dashboard einzeln pro Schüler hochgeladen werden. Das Foto wird serverseitig gespeichert und auf dem Ausweis angezeigt. Beim CSV-Import wird ein Hash des Fotos gespeichert, sodass bei späteren Imports nur geänderte Fotos aktualisiert werden.Student photos can be uploaded individually per student in the admin dashboard. The photo is stored server-side and displayed on the ID. During CSV import, a hash of the photo is stored so that only changed photos are updated in later imports.

Lehrkräfte können ihr Foto selbst über die PWA hochladen — direkt aus der Ausweis-App heraus. Für Schülerinnen und Schüler erfolgt der Upload ausschließlich über das Admin-Dashboard durch die Schulverwaltung.Teachers can upload their own photo directly through the PWA — from within the ID card app. For students, photo upload is exclusively done through the admin dashboard by school administration.

7.4 Schüler deaktivieren oder löschen7.4 Deactivating or Deleting Students

Einzelne Schüler können vom Schuladmin manuell deaktiviert werden (z. B. bei Schulverweis). Der Ausweis wird dann sofort ungültig. Bei der nächsten endgültigen Löschung (nach der 4-Wochen-Frist) werden alle personenbezogenen Daten unwiderruflich entfernt.Individual students can be manually deactivated by the school admin (e.g., in case of expulsion). The ID then becomes immediately invalid. Upon permanent deletion (after the 4-week grace period), all personal data is irreversibly removed.

7.5 Gültigkeit und Schuljahreswechsel7.5 Validity and School Year Transitions

Jede Schule kann eine Gültigkeitsstrategie für Ausweise festlegen: automatisch bis zum Ende des aktuellen Schulhalbjahres oder ein festes Datum. Beim Schuljahreswechsel wird die Gültigkeit durch einen neuen CSV-Import aktualisiert. Schüler, die nicht mehr in der CSV auftauchen, werden automatisch zur Löschung vorgemerkt.Each school can set an ID validity strategy: automatically until the end of the current school term or a fixed date. At the school year transition, validity is updated through a new CSV import. Students who no longer appear in the CSV are automatically marked for deletion.

7.6 Schul- und Dienstbescheinigungen (optional)7.6 Enrollment and Employment Certificates (optional)

Schulen können pro Klasse freischalten, dass Schülerinnen und Schüler direkt aus der App eine Schulbescheinigung als PDF herunterladen (Lehrkräfte entsprechend eine Dienstbescheinigung). Das Dokument trägt einen dauerhaften Verifizierungs-QR-Code: Beim Scannen zeigt der Server den aktuellen Live-Status — aktiv eingeschrieben oder nicht. Eine Bescheinigung „widerruft sich“ damit automatisch, sobald die Person die Schule verlässt. Briefkopf, Logo und Textbausteine sind pro Schule anpassbar.Schools can enable, per class, that students download an enrollment certificate as a PDF directly from the app (teachers receive an employment certificate accordingly). The document carries a permanent verification QR code: when scanned, the server shows the current live status — actively enrolled or not. A certificate thus “revokes itself” automatically as soon as the person leaves the school. Letterhead, logo and text blocks are customizable per school.

SystemkomponentenSystem Components

Hagen-ID besteht aus vier Docker-Containern, die als Einheit betrieben werden:Hagen-ID consists of four Docker containers that are operated as a unit:

KomponenteComponent	TechnologieTechnology	FunktionFunction
DatenbankDatabase	PostgreSQL 16	Persistente Datenspeicherung aller Schüler- und VerwaltungsdatenPersistent storage of all student and administrative data
API-ServerAPI Server	Python / FastAPI	Geschäftslogik, Authentifizierung, QR-Code-Verifizierung, CSV-Import, Sync-APIBusiness logic, authentication, QR code verification, CSV import, sync API
Admin-DashboardAdmin Dashboard	React (SPA)	Weboberfläche für die SchulverwaltungWeb interface for school administration
Schüler-PWAStudent PWA	React (PWA)	Digitaler Ausweis auf dem Smartphone (für Schüler und Lehrkräfte)Digital ID on the smartphone (for students and teachers)

Systemarchitektur: Hagen-ID — Docker-Container, Netzwerksegmentierung, Datenflüsse

Hosting und InfrastrukturHosting and Infrastructure

Die Anwendung wird auf einem dedizierten Server oder einer VM betrieben. Für den produktiven Einsatz steht eine gehärtete Docker-Compose-Konfiguration bereit, die folgende Sicherheitsmaßnahmen umfasst:The application runs on a dedicated server or VM. For production use, a hardened Docker Compose configuration is available with the following security measures:

Netzwerksegmentierung:Network Segmentation: Die Datenbank befindet sich in einem internen Docker-Netzwerk ohne Internetzugang. Nur der API-Server kann mit der Datenbank kommunizieren. Die Frontends kommunizieren ausschließlich über die API.The database is on an internal Docker network with no internet access. Only the API server can communicate with the database. Frontends communicate exclusively through the API.
Read-only Filesystems:Read-only Filesystems: Container-Dateisysteme sind schreibgeschützt, um das Einschleusen von Schadcode zu verhindern.Container filesystems are read-only to prevent malicious code injection.
Ressourcenbegrenzung:Resource Limits: CPU- und Speicherlimits pro Container verhindern, dass ein einzelner Dienst den gesamten Server belastet.CPU and memory limits per container prevent a single service from overloading the entire server.
TLS/HTTPS: Die gesamte Kommunikation zwischen Browser und Server erfolgt verschlüsselt über HTTPS. Die TLS-Terminierung erfolgt über einen vorgeschalteten Reverse Proxy (Nginx oder Coolify).All communication between browser and server is encrypted via HTTPS. TLS termination is handled by a reverse proxy (Nginx or Coolify).
Automatische Backups:Automatic Backups: Ein Backup-Skript sichert die Datenbank täglich. Backups können automatisiert an einen externen Speicherort übertragen werden.A backup script secures the database daily. Backups can be automatically transferred to an external storage location.

Sicherheitsmaßnahmen im ÜberblickSecurity Measures Overview

MaßnahmeMeasure	BeschreibungDescription
JWT-AuthentifizierungAuthentication	Signierte Tokens mit Ablaufzeit (HS256, mind. 32 Zeichen Secret), Auslieferung als HttpOnly-CookieSigned tokens with expiration time (HS256, min. 32 character secret), delivered as HttpOnly cookies
bcrypt-Passwort-HashingPassword Hashing	Brute-Force-resistentes Hashing mit automatischem SaltBrute-force resistant hashing with automatic salt
Verschlüsselung at-restEncryption at rest	Namen, Geburtsdaten, Fotos, PINs und TOTP-Secrets liegen verschlüsselt in der Datenbank (Fernet); der Schlüssel liegt außerhalb der DBNames, dates of birth, photos, PINs and TOTP secrets are stored encrypted in the database (Fernet); the key is kept outside the DB
Row-Level-Security	Mandantentrennung zusätzlich auf Datenbankebene erzwungen (PostgreSQL RLS)Tenant separation additionally enforced at the database level (PostgreSQL RLS)
Rate Limiting	5 Fehlversuche pro 15 Minuten, dann temporäre Sperre — pro Konto und pro IP; Grenzen serverseitig fest verankert5 failed attempts per 15 minutes, then temporary block — per account and per IP; limits enforced server-side
CORS-WhitelistWhitelist	Nur explizit erlaubte Domains können auf die API zugreifenOnly explicitly allowed domains can access the API
Gerätegebundene SignaturenDevice-bound Signatures	QR-Codes werden auf dem Gerät signiert (ECDSA P-256, WebCrypto); der private Schlüssel ist nicht exportierbar und verlässt das Gerät nieQR codes are signed on the device (ECDSA P-256, WebCrypto); the private key is non-extractable and never leaves the device
TOTP (RFC 6238)	Zeitbasierte Einmalcodes mit 30-Sekunden-IntervallTime-based one-time codes with 30-second intervals
Highlander-SessionHighlander Session	Nur ein aktives Gerät pro Schüler, Token- und Schlüssel-Invalidierung bei neuem LoginOnly one active device per student; token and key invalidation on new login
API-Key-AuthentifizierungAuthentication	Schulspezifische API-Keys für die Sync-Schnittstelle (SHA-256-Hash in DB, einmalig sichtbar); optional zusätzlich per IP-Allowlist abgesichertSchool-specific API keys for the sync interface (SHA-256 hash stored in DB, shown once only); optionally secured further with an IP allowlist
Pseudonymes Audit-LogPseudonymous Audit Log	Sicherheitsereignisse mit 180-Tage-Aufbewahrung; Detail-Nachverfolgung nur zeitlich begrenzt im VerdachtsfallSecurity events with 180-day retention; detailed tracing only time-limited in suspicious cases
Security Headers	CSP, X-Frame-Options, X-Content-Type-Options, HSTS via Reverse Proxy

VoraussetzungenRequirements

Ein Linux-Server oder eine VM mit mindestens 2 GB RAM und 20 GB SpeicherA Linux server or VM with at least 2 GB RAM and 20 GB storage
Docker und Docker Compose
Eine Domain mit TLS-Zertifikat (z. B. via Let's Encrypt)A domain with TLS certificate (e.g., via Let's Encrypt)
Zugang zur Schulverwaltungssoftware für den CSV-Export der SchülerdatenAccess to school administration software for CSV export of student data

EinführungsprozessRollout Process

1. Server einrichtenSet up server → 2. Hagen-ID deployenDeploy Hagen-ID → 3. Schule konfigurierenConfigure school → 4. Daten importierenImport data → 5. PINs verteilenDistribute PINs

Im ersten Schritt wird der Server mit der gehärteten Docker-Compose-Konfiguration eingerichtet. Anschließend wird die Schule im System angelegt (Name, Logo, Farben, URL-Pfad). Danach erfolgt der erste CSV-Import der Schülerdaten. Die generierten Login-PINs werden ausgedruckt und über die Klassenlehrkräfte an die Schülerinnen und Schüler verteilt.In the first step, the server is set up with the hardened Docker Compose configuration. Next, the school is created in the system (name, logo, colors, URL path). Then, the first CSV import of student data takes place. The generated login PINs are printed and distributed to students through their class teachers.

Zeitaufwand:Time Required: Die technische Einrichtung ist innerhalb eines Arbeitstages abgeschlossen. Der organisatorische Rollout (PIN-Verteilung, Einführung im Kollegium) kann parallel vorbereitet und in der ersten Schulwoche durchgeführt werden.Technical setup is completed within one business day. The organizational rollout (PIN distribution, staff introduction) can be prepared in parallel and conducted during the first school week.

Laufender BetriebOngoing Operations

Regelmäßiger CSV-Import:Regular CSV Import: Bei Änderungen im Schülerbestand (Zu- und Abgänge, Klassenwechsel) wird eine aktualisierte CSV-Datei hochgeladen. Das System erkennt Änderungen automatisch.When student roster changes occur (additions, departures, class changes), an updated CSV file is uploaded. The system automatically detects changes.
Automatische Backups:Automatic Backups: Die Datenbank wird täglich gesichert.The database is backed up daily.
Automatische Bereinigung:Automatic Cleanup: Soft-gelöschte Datensätze werden nach 4 Wochen endgültig entfernt.Soft-deleted records are permanently removed after 4 weeks.
Updates: Neue Versionen können per Docker-Image-Update eingespielt werden, ohne Datenverlust.New versions can be deployed via Docker image updates without data loss.

Betrieb über Coolify (empfohlen)Operations via Coolify (Recommended)

Für Schulen ohne dediziertes IT-Personal empfehlen wir den Betrieb über Coolify — eine Self-Hosting-Plattform mit grafischer Oberfläche. Coolify übernimmt automatisch die TLS-Zertifikatsverwaltung, ermöglicht einfache Deployments und Rollbacks über ein Web-UI und reduziert den operativen Aufwand erheblich.For schools without dedicated IT staff, we recommend running it via Coolify — a self-hosting platform with a graphical interface. Coolify automatically handles TLS certificate management, enables simple deployments and rollbacks via web UI, and significantly reduces operational overhead.

Sie möchten Hagen-ID an Ihrer Schule einsetzen oder haben Fragen zur technischen Umsetzung, zum Datenschutzkonzept oder zur Einführung? Nehmen Sie gerne Kontakt auf:Would you like to implement Hagen-ID at your school, or do you have questions about technical implementation, data protection, or rollout? Please get in touch:

Demonstration & BeratungDemo & Consultation

Wir zeigen Ihnen das System in einer Live-Demo und beantworten alle Fragen zu Funktionsumfang, Datenschutz und Einführung.We'll show you the system in a live demo and answer all your questions about features, data protection, and implementation.

PilotprojektPilot Project

Starten Sie mit einer einzelnen Klasse oder Jahrgangsstufe, um das System im Schulalltag zu erproben, bevor Sie den Rollout auf die gesamte Schule ausweiten.Start with a single class or grade level to test the system in your school environment before rolling out to the entire school.

QuellcodeSource Code

Hagen-ID ist Open Source (AGPL-3.0). Der vollständige Quellcode ist auf GitHub einsehbar und kann von Ihrer IT-Abteilung oder externen Gutachtern geprüft werden — die Nutzung ist kostenlos.Hagen-ID is open source (AGPL-3.0). The complete source code is available on GitHub and can be reviewed by your IT department or external auditors — use is free of charge.

Kontakt aufnehmen Get in touch Quellcode auf GitHub Source on GitHub