- JavaScript 97.8%
- Shell 1.6%
- Dockerfile 0.6%
|
|
||
|---|---|---|
| deploy | ||
| docs | ||
| src | ||
| test | ||
| tools | ||
| .dockerignore | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| cliff.toml | ||
| Dockerfile | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
fedilogin
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/appsmit minimalem Scope (profile, sonstread:accounts) und speichert client_id/secret. - OAuth Authorization Code mit
client_secretund 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>undpreferred_username=user@instanz. Keine E-Mail.name,picture,profilenur, wenn der Betreiber sie mitEXTRA_CLAIMSeinschaltet. 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 eingebautenode: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, setztX-Forwarded-Protound hängt die Client-IP anX-Forwarded-Foran. Die Endpunkt-URLs werden aus der Anfrage gebildet, die Client-IP ist die letzte Adresse inX-Forwarded-For. Der Dienst darf deshalb nur über den Proxy erreichbar sein. - Der Proxy setzt bzw. überschreibt
X-Forwarded-Hostmit dem Host desISSUER(oder reicht den Header gar nicht durch). Anfragen, deren Host nicht zumISSUERpasst, 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): …→ Addedfix(scope): …→ Fixedperf(scope): …→ Performancerefactor(scope): …→ ChangedBREAKING 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.