Dein Toot-Konto ist dein Ausweis 🐘🔑
  • JavaScript 97.8%
  • Shell 1.6%
  • Dockerfile 0.6%
Find a file
holm / Christian Müller 19973cbe1b
Merge branch 'dev' into main (v0.3.0)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:13:21 +01:00
deploy fix: Härtung aus dem Security-Audit 2026-11-16 10:11:42 +01:00
docs fix: Härtung aus dem Security-Audit 2026-11-16 10:11:42 +01:00
src fix: Härtung aus dem Security-Audit 2026-11-16 10:11:42 +01:00
test fix: Härtung aus dem Security-Audit 2026-11-16 10:11:42 +01:00
tools test: Werkzeug für die lokale Abnahme gegen eine echte Instanz 2026-11-15 23:36:17 +01:00
.dockerignore feat(deploy): Dockerfile, Compose-Vorlage, env-Beispiel und Keycloak-Anleitung 2026-11-15 23:55:43 +01:00
.gitignore chore: Standard-Dateien ergänzen 2026-11-15 23:11:34 +01:00
CHANGELOG.md chore(release): v0.3.0 2026-11-16 10:13:12 +01:00
CLAUDE.md chore: Standard-Dateien ergänzen 2026-11-15 23:11:34 +01:00
cliff.toml chore: Standard-Dateien ergänzen 2026-11-15 23:11:34 +01:00
Dockerfile fix(proxy): Healthcheck über /healthz statt Discovery 2026-11-16 09:55:52 +01:00
LICENSE chore: Standard-Dateien ergänzen 2026-11-15 23:11:34 +01:00
package-lock.json chore: Version 0.3.0 in package.json 2026-11-16 10:13:02 +01:00
package.json chore: Version 0.3.0 in package.json 2026-11-16 10:13:02 +01:00
README.md fix: Härtung aus dem Security-Audit 2026-11-16 10:11:42 +01:00

fedilogin

License: MIT Node OIDC

Fediverse-Login als ein einziger OpenID-Connect-Provider: Konten beliebiger Instanzen (Mastodon, GoToSocial, Pleroma, Akkoma, Friendica …) melden sich bei einer Relying Party wie Keycloak an.

Features

  • Ein OIDC-Provider für viele Instanzen: Die Relying Party kennt nur fedilogin. Wer sich anmeldet, nennt seine Instanz und meldet sich dort an.
  • Selbstregistrierung je Instanz: Beim ersten Login einer Instanz registriert sich fedilogin per POST /api/v1/apps mit minimalem Scope (profile, sonst read:accounts) und speichert client_id/secret.
  • OAuth Authorization Code mit client_secret und PKCE S256: PKCE wird immer mitgeschickt. Instanzen, die es nicht kennen, ignorieren es.
  • PKCE auch für die Relying Party: Jede Anfrage einer Relying Party muss PKCE (S256) mitbringen, sonst invalid_request.
  • Datensparsam: Standardmäßig nur sub = <account-id>@<instanz> und preferred_username = user@instanz. Keine E-Mail. name, picture, profile nur, wenn der Betreiber sie mit EXTRA_CLAIMS einschaltet. Siehe Datenschutz.
  • Schutz: nur konfigurierte Relying Parties, Sperr-/Erlaubnisliste für Instanzen, Limits für neue Instanzen (global pro Stunde, nur für geprüfte Instanzen, und je Client-IP: 10 in 10 Minuten), Anmeldeversuche je Client-IP (60 in 10 Minuten; IPv6 je /64), 10 Minuten Sperre nach fehlgeschlagener Instanzprüfung, SSRF-Schutz (keine IP-Literale, keine privaten Adressen, keine Weiterleitungen, Zeit- und Größenlimits, höchstens 4 gleichzeitige Anfragen je Instanz und 32 insgesamt), geprüfte Kontokennungen und App-Zugangsdaten, CSP mit frame-ancestors 'none'.
  • Eine Laufzeit-Abhängigkeit: oidc-provider (OpenID-zertifiziert). SQLite über das eingebaute node:sqlite.

Unterstützte Server-Software

PKCE-Stand aus dem Quellcode (November 2026):

Software Mastodon-Client-API PKCE S256
Mastodon ≥ 4.3 ja ja (optional)
GoToSocial ja ja (optional)
Pleroma / Akkoma ja nein, client_secret
Friendica ja nein, client_secret
Pixelfed ja vermutlich (Laravel Passport)
Misskey-Familie eigenes OAuth/MiAuth späterer Adapter

Abgenommen gegen echte Instanzen: noch keine (geplant: Mastodon).

Aufruf

npm ci --omit=dev
ISSUER=https://login.example.org \
COOKIE_KEYS=$(openssl rand -hex 32) \
OIDC_CLIENTS='[{"client_id":"keycloak","client_secret":"…","redirect_uris":["https://sso.example.org/realms/demo/broker/fediverse/endpoint"]}]' \
DATA_DIR=/data \
node src/index.js

Umgebungsvariablen

Variable Pflicht Default Bedeutung
ISSUER ja – Öffentliche Basis-URL (https), ohne abschließenden /
COOKIE_KEYS ja – Komma-getrennte Schlüssel zum Signieren der Cookies, je ≥ 32 Zeichen
OIDC_CLIENTS ja – JSON-Array der Relying Parties: client_id, client_secret (≥ 16 Zeichen), redirect_uris; optional post_logout_redirect_uris, token_endpoint_auth_method (client_secret_basic Default, oder client_secret_post), preset_instances (Instanzen, die der Client per instance= vorgeben darf, siehe docs/keycloak.md)
DATA_DIR nein ./data Verzeichnis für fedilogin.sqlite und ggf. jwks.json
OIDC_JWKS nein – Signaturschlüssel als JWKS-JSON; fehlt er, wird ein RSA-Schlüssel in DATA_DIR/jwks.json erzeugt
PORT nein 3000 HTTP-Port (TLS terminiert der Reverse-Proxy)
INSTANCE_ALLOWLIST nein – Komma-getrennte Hosts; gesetzt = nur diese. Exakter Treffer; Subdomains nur mit *.domain (dann ohne domain selbst)
INSTANCE_DENYLIST nein – Komma-getrennte Domains, die abgewiesen werden (inkl. Subdomains)
APP_REGISTRATIONS_PER_HOUR nein 20 Höchstzahl neuer App-Registrierungen pro Stunde
APP_NAME nein fedilogin Name der App, wie ihn die Instanz beim Login zeigt
APP_WEBSITE nein ISSUER Website der App bei der Instanz
EXTRA_CLAIMS nein – Zusätzliche Claims, komma-getrennt aus name, picture, profile (Standard: keine)
ALLOW_INSECURE_INSTANCES nein false Nur für Tests: erlaubt http:// und private Adressen

Keycloak

Identity Provider vom Typ „OpenID Connect v1.0" anlegen, Discovery-URL <ISSUER>/.well-known/openid-configuration, Client-Authentifizierung passend zu token_endpoint_auth_method („Client secret sent as basic auth" bzw. „… as post"), Scopes openid profile. Als Benutzername eignet sich preferred_username (user@instanz), E-Mail liefert fedilogin nicht. Ausführlich: docs/keycloak.md.

Datenschutz

Grundsatz: Was nicht gespeichert ist, muss nicht geschützt oder gelöscht werden.

Was Wo Wie lange
App-Registrierung je Instanz (client_id/secret, Software-Version) instance_apps dauerhaft; keine Personendaten
Laufender Login (state, PKCE-Verifier, Instanz) pending_logins max. 10 Minuten
Claims eines Logins (sub, preferred_username, ggf. EXTRA_CLAIMS) accounts so lange wie das Access-Token (1 Stunde), dann gelöscht
Sessions, Codes, Tokens von oidc-provider oidc_store bis zum Ablauf (Session 1 h, Code 60 s, Token 1 h; eine Session wird nie für einen neuen Login wiederverwendet)
Token der Instanz nirgends wird direkt nach verify_credentials bei der Instanz zurückgegeben
Logs stdout nur Instanz-Host und Fehlercode, keine Konten

fedilogin fragt bei der Instanz nur den kleinsten Scope an (profile bzw. read:accounts) und liest einmal das eigene Konto.

Container

docker build -t fedilogin .

Vorlagen für den Betrieb: deploy/compose.example.yml (Daten auf NFS v4.2, kein Port nach außen) und deploy/env.example. Das Image läuft als uid 1000 mit Healthcheck auf /healthz (ohne Host-Prüfung, liefert nur ok). Keycloak anbinden: docs/keycloak.md.

Voraussetzungen

  • Node.js ≥ 24 (node:sqlite)
  • Reverse-Proxy mit TLS vor dem Dienst. Er reicht den Host-Header durch, setzt X-Forwarded-Proto und hängt die Client-IP an X-Forwarded-For an. Die Endpunkt-URLs werden aus der Anfrage gebildet, die Client-IP ist die letzte Adresse in X-Forwarded-For. Der Dienst darf deshalb nur über den Proxy erreichbar sein.
  • Der Proxy setzt bzw. überschreibt X-Forwarded-Host mit dem Host des ISSUER (oder reicht den Header gar nicht durch). Anfragen, deren Host nicht zum ISSUER passt, beantwortet der Dienst mit 400.
  • Persistenter Speicher für DATA_DIR. Im Container-Betrieb extern (z. B. NFS v4.2), nicht auf dem Container-Host.

Tests

npm test

Die Ende-zu-Ende-Tests spielen den kompletten Ablauf gegen eine nachgebaute Mastodon-Instanz durch (Relying Party → fedilogin → Instanz → zurück → Token).

Abnahme gegen eine echte Instanz

bash tools/abnahme-lokal.sh

Startet fedilogin (http://localhost:3000) und eine Test-Relying-Party (http://localhost:3001), die nach dem Login die Claims aus ID-Token und Userinfo zeigt. Die Instanz leitet nur den Browser zurück, sie muss fedilogin nicht erreichen können. Mastodon erlaubt http://localhost als Redirect-URI.

Changelog

Siehe CHANGELOG.md. Wird per git-cliff aus Conventional Commits generiert. Manuell nicht editieren — stattdessen Commit-Messages sauber halten:

  • feat(scope): … → Added
  • fix(scope): … → Fixed
  • perf(scope): … → Performance
  • refactor(scope): … → Changed
  • BREAKING CHANGE: … im Body → Major-Bump

Installation

git clone https://forgejo.mueller.network/holm.tools.public/fedilogin.git
cd fedilogin
npm ci --omit=dev

Lizenz

MIT — Copyright (c) 2026 holm / Christian Müller, unter Zuhilfenahme von Claude.ai (Anthropic).

Siehe LICENSE.