Authentifizierungsrichtlinie

Die Seite zur Authentifizierungsrichtlinie bündelt die organisationsweiten Einstellungen, die festlegen, wie sich deine Mitglieder bei Git und der REST-API authentifizieren. Jeder Schalter ist unabhängig von den anderen. Die Standardwerte sind jeweils die großzügigsten, damit bestehende Mitglieder nicht überraschend ausgesperrt werden, wenn du die Seite zum ersten Mal öffnest. Verschärfe sie einzeln, so wie deine Sicherheitsanforderungen wachsen.

Du findest sie unter Sicherheit › Zugriff › Authentifizierungsrichtlinie (<your-org>/_admin/security/access/authentication; die ältere Adresse <your-org>/_admin/auth-policy leitet dorthin weiter). Oben auf der Seite stehen außerdem die Informationen zur Zwei-Faktor-Authentifizierung, die früher auf der eingestellten Seite für Edge-Richtlinien lagen: Zwei-Faktor-Authentifizierung ist immer Pflicht, für jedes Mitglied.

Zusammenlegung am 2026-05-26: Der eigenständige Tab SSH-Zertifizierungsstelle ist als Unterabschnitt von „SSH-Protokoll erlauben“ in diese Seite gewandert (er ergibt nur Sinn, wenn SSH aktiviert ist, und erscheint deshalb zusammen mit dem Schalter). Direkte Links auf /admin/ssh-ca/ leiten jetzt hierher weiter. Die Bearbeitungsmöglichkeiten sind dieselben geblieben: CA-Schlüssel einfügen, Zertifikatspflicht umschalten, ohne die Ansicht der Authentifizierungsrichtlinie zu verlassen.

Richtlinien

Anforderungen an SSH-Schlüssel

Ist diese Option aktiv, lehnt fremforge neue SSH-Schlüssel ab, die nicht hardwaregestützt sind. Das erkennen wir am OpenSSH-Schlüsselalgorithmus: Nur sk-ssh-ed25519@openssh.com und sk-ecdsa-sha2-nistp256@openssh.com erfüllen die Anforderung. Einfache ssh-ed25519- und ssh-rsa-Schlüssel werden im Formular Schlüssel hinzufügen abgewiesen.

Hardwaregestützt heißt, dass der private Schlüssel in einem Sicherheitschip liegt (macOS Secure Enclave, TPM, YubiKey, FIDO-Authenticator). Der Schlüssel lässt sich nicht vom Laptop extrahieren. Bei jedem Push ist Touch ID, eine PIN oder eine Berührung der Hardware nötig. Das kommt „MFA bei git push“ am nächsten, ohne eine vollständige SSH-Zertifizierungsstelle aufzubauen.

Bestehende Schlüssel werden NICHT rückwirkend abgelehnt, nur das Hinzufügen neuer Schlüssel wird geprüft. Du kannst die Option also gefahrlos in einer laufenden Organisation einschalten: Mitglieder pushen mit ihren vorhandenen Schlüsseln weiter, aber wer einen neuen Laptop einrichtet, muss einen hardwaregestützten Schlüssel verwenden. Kombiniere sie mit der SSH-Zertifizierungsstelle weiter unten für den stärksten Endzustand (überhaupt keine einfachen Schlüssel mehr).

Aktionen im Audit-Log: tenant.auth_policy.hardware_keys.enabled / tenant.auth_policy.hardware_keys.disabled.

SSH-Zertifizierungsstelle

(Nur sichtbar, wenn das SSH-Protokoll oben aktiviert ist. Eine SSH-Funktion erst dann einzublenden, wenn SSH an ist, ist das naheliegende Muster.)

Die Authentifizierung mit SSH-Zertifikaten ist der stärkste praktikable Weg, sich per SSH anzumelden. Ein kurzlebiges Zertifikat, ausgestellt von deiner eigenen CA und an den MFA-Ablauf deines IdP gebunden, ersetzt den langlebigen öffentlichen Schlüssel, der auf jedem Entwickler-Laptop liegt. fremforge unterstützt dieses Modell nativ, dasselbe Prinzip, das GitHub Enterprise Cloud „SSH certificate authority“ nennt.

Voraussetzung: Seit dem 2026-05-22 legt fremforge neue Organisationen mit deaktiviertem SSH an (der Schalter oben). Behält deine Organisation diesen Standard bei, brauchst du überhaupt keine SSH-CA: Der Weg über HTTPS + Git Credential Manager gibt dir MFA bei jedem Push über deinen IdP, ganz ohne CA. Hat deine Organisation SSH ausdrücklich wieder aktiviert (weil es einen konkreten Grund gibt, etwa alte CI-Werkzeuge oder eine starke Vorliebe deiner Entwickler), ist dieser Abschnitt die nächste Härtungsstufe für diesen bewusst gewählten SSH-Weg.

Wann sich eine SSH-CA lohnt

Setze auf Authentifizierung mit SSH-Zertifikaten, wenn deine Organisation SSH wieder aktiviert hat UND einer der folgenden Punkte zutrifft:

• Jeder Git-Push soll durch eine frische MFA-Abfrage beim IdP abgesichert sein (kein „Laptop verloren → Angreifer pusht 90 Tage lang, bis jemand den SSH-Schlüssel bemerkt“)
• Du ziehst von GitHub Enterprise Cloud um, und deine Entwickler erwarten den SSH-CA-Ablauf von GHEC
• Deine CISO verlangt ausdrücklich „MFA bei Git-Push“ UND besteht auf SSH als Transport; die sauberere Antwort ist allerdings der Standardweg über HTTPS + GCM
• Du betreibst bereits eine CA, die OpenSSH-Zertifikate ausstellt (Smallstep, die SSH Secrets Engine von HashiCorp Vault, ein eigener OIDC-gebundener Aussteller), und fremforge soll den von ihr signierten Zertifikaten vertrauen

Trifft nichts davon zu, sind hardwaregestützte SSH-Schlüssel (Touch ID, Secure Enclave, YubiKey, Schalter oben) der einfachere Weg mit vergleichbarer Sicherheit. Eine Entscheidungshilfe findest du unter Sichere Anmeldung.

Einrichtung

Schritt 1: Bereite deine CA vor. Die Optionen, nach Aufwand sortiert:

1. Smallstep step ca: Open Source, gut in der EU zu betreiben, mit OIDC-Provisioner von Haus aus. Binde sie an deinen IdP, und step ssh login wird zu einem einzeiligen MFA-Ablauf.
2. HashiCorp Vault SSH Secrets Engine: Betreibst du Vault bereits für Secrets, ergänzt die SSH Secrets Engine die Ausstellung von OpenSSH-Zertifikaten mit richtlinienbasierter Zugriffskontrolle.
3. Manuell mit ssh-keygen -s: nur als Machbarkeitsnachweis.

Erzeuge das CA-Schlüsselpaar, falls du noch keines hast:

ssh-keygen -t ed25519 -f acme-ssh-ca -C "acme-ssh-ca@example.com"

Das ergibt acme-ssh-ca (privat: geheim halten und an deine ausstellende Infrastruktur verteilen) und acme-ssh-ca.pub (öffentlich: kommt im nächsten Schritt in fremforge).

Schritt 2: Registriere die CA. Füge acme-ssh-ca.pub auf dieser Seite in das Textfeld Öffentliche CA-Schlüssel (einer pro Zeile) ein, eine CA pro Zeile. Bis zu 8 CAs werden akzeptiert (praktisch für die Rotation: neue hinzufügen, neuen privaten Schlüssel verteilen, alte entfernen). Klicke auf Save CA keys. Ein automatischer Plattform-Job überträgt die Änderung in die SSH-Schicht von Forgejo. Eintrag im Audit-Log: tenant.ssh_ca.keys.updated.

Schritt 3: Lass Mitglieder ihre Principals registrieren. Jedes SSH-Zertifikat trägt einen oder mehrere Principals, kurze Zeichenketten, die angeben, für wen es ist. Ein von einer vertrauenswürdigen CA signiertes Zertifikat meldet ein Mitglied an, wenn einer seiner Principals mit einem Principal übereinstimmt, den das Mitglied auf seiner eigenen Einstellungsseite für SSH-Schlüssel registriert hat (im Abschnitt Manage SSH certificate principals). fremforge akzeptiert dort jede beliebige Zeichenkette, stelle also Zertifikate aus, deren Principal den Nutzer eindeutig benennt, zum Beispiel mit seinem fremforge-Benutzernamen.

Entfernt am 2026-10-14: die Einstellung „Principal policy“ (Username / Email / Anything). Sie wurde gespeichert, aber nie durchgesetzt: Forgejo prüft die Form eines Principals anhand einer einzigen plattformweiten Einstellung, nicht pro Organisation, und ein Mitglied kann mehreren Organisationen angehören. PUT /orgs/{org}/ssh-ca in der API akzeptiert principal_policy weiterhin, damit bestehende Skripte und Terraform-Konfigurationen funktionieren, ignoriert es aber, und GET gibt es nicht mehr zurück.

Schritt 4: Verlange optional die Zertifikatsauthentifizierung. Sobald mindestens eine CA eingerichtet ist, schalte CA-signiertes Zertifikat verlangen (keine einfache Authentifizierung per öffentlichem Schlüssel) ein, um die einfache Authentifizierung per öffentlichem SSH-Schlüssel abzulehnen. Das ist der sauberste Endzustand: Langlebige ~/.ssh/id_*-Schlüssel funktionieren gar nicht mehr, jeder Git-Push muss über deine CA laufen (und damit über den MFA-Ablauf deines IdP). Ohne funktionierende CA würde das alle aussperren; das Formular verweigert die Änderung deshalb, solange keine CA eingerichtet ist. Einträge im Audit-Log: tenant.ssh_ca.require_cert.enabled / tenant.ssh_ca.require_cert.disabled.

Schritt 5: Stelle Nutzern ihr erstes Zertifikat aus. Mit Smallstep:

step ssh login user@example.com --provisioner=your-oidc-provisioner
# Browser opens → IdP login + MFA → cert issued + cached ~1 hour.

git clone git@frem.sh:<org>/<repo>.git
# OpenSSH presents the cert; fremforge checks the trusted CA and the user's registered principals.

Für Vault siehe die Dokumentation der HashiCorp Vault SSH Secrets Engine. Manuell mit ssh-keygen -s (nur als Machbarkeitsnachweis): ssh-keygen -s acme-ssh-ca -I "alice-cert-2026-05-22" -n alice -V +1h alice-id_ed25519.pub → gib alice-id_ed25519-cert.pub zusammen mit dem privaten Schlüssel an den Nutzer weiter; OpenSSH greift automatisch darauf zurück.

Die CA rotieren

So ersetzt du eine bestehende CA ohne Ausfall: Erzeuge ein neues CA-Schlüsselpaar → füge den neuen öffentlichen Schlüssel neben dem bestehenden in das Textfeld ein (bis zu 8 werden akzeptiert) → stelle deine CA-Infrastruktur auf den neuen Schlüssel um → warte, bis die von der alten CA ausgestellten Zertifikate abgelaufen sind (meist 1 Stunde) → entferne die alte CA aus dem Textfeld.

CA-Authentifizierung abschalten

Entferne alle CA-Schlüssel aus dem Textfeld und speichere. Der Audit-Log-Eintrag tenant.ssh_ca.keys.updated hält next_key_count: 0 fest. War CA-signiertes Zertifikat verlangen eingeschaltet, schaltet es sich automatisch ab (der Schalter setzt mindestens eine CA voraus). Mitglieder authentifizieren sich dann wieder einfach per öffentlichem SSH-Schlüssel.

PAT-Laufzeit

Die maximal erlaubte Laufzeit neu erstellter persönlicher Zugriffstoken. Bestehende Token werden NICHT rückwirkend verkürzt, die Grenze gilt nur bei der Ausstellung.

Empfehlung: 90 Tage als Ausgangspunkt. Verkürze auf 30, wenn du ein aktives Credential-Scanning betreibst, das geleakte Token innerhalb des Rotationsfensters findet.

Aktion im Audit-Log: tenant.auth_policy.max_pat_lifetime.updated.

Repo-Deploy-Keys erlauben

Repo-Deploy-Keys sind langlebige SSH-Zugangsdaten für ein einzelnes Repository, ein zweiter Weg zu langlebigen Maschinen-Zugangsdaten neben den PATs der Nutzer. Nützlich für externe CI- oder Spiegel-Clients, die sich nicht per OIDC föderieren lassen. Standard: aus, passend zur sicheren Grundeinstellung von ssh_disabled=true und allow_user_pats=false. Langlebige Maschinen-Zugangsdaten bleiben aus, bis du sie bewusst einschaltest.

Ist die Richtlinie aus (Standard), greifen drei Ebenen:

1. Hinweisbanner in Forgejo: Öffnet ein Repo-Administrator Repository → Einstellungen → Deploy-Schlüssel, wird die Seite über api-intercept geleitet, das oberhalb des normalen Forgejo-Headers ein Banner im Fomantic-Stil einfügt, das erklärt, dass Deploy-Keys durch die Richtlinie der Organisation deaktiviert sind. Navigation und Seitenleiste von Forgejo bleiben erhalten (der Nutzer wird nie aus dem Repo geworfen). Das Absenden des Formulars Add deploy key wird in der API blockiert (der POST wird per 303 auf den GET zurückgeleitet, sodass der Nutzer die Erklärung im Banner sieht).
2. Sperre in der REST-API: POST /api/v1/repos/<owner>/<repo>/keys antwortet mit 403, error: use_fremforge_admin und einem redirect_to, das hierher zeigt. DELETE und GET werden immer durchgereicht (bestehende Schlüssel lassen sich unabhängig von der Richtlinie aufräumen und prüfen).
3. Hinweis im Audit-Log: Jeder bestehende aktive Deploy-Key erzeugt beim nächsten Durchlauf der Durchsetzung ein Audit-Ereignis tenant.auth_policy.deploy_key_violation. Bestehende Schlüssel werden NICHT automatisch widerrufen; welche entfernt werden, entscheidest du in den Repo-Einstellungen von Forgejo (das Löschen bleibt möglich).

Wann einschalten: nur im Sonderfall externer CI- oder Spiegel-Clients, die sich wirklich nicht per OIDC föderieren lassen. Die vorgesehene Alternative für die Maschinenidentität in der CI ist die OIDC-Föderation für Runner: kurzlebige Token aus dem OIDC-Issuer von fremforge, föderiert mit der Vertrauensrichtlinie deiner Cloud, ohne langlebiges Secret pro Repo. Die meisten CI-Integrationen brauchen keine Deploy-Keys.

Aktionen im Audit-Log: tenant.auth_policy.allow_repo_deploy_keys.enabled / .disabled (Schalter); tenant.auth_policy.deploy_key_violation (pro aktivem Schlüssel, solange die Richtlinie aus ist).

Signierte Commits verlangen

Ist diese Option aktiv, trägt der Standard-Branch jedes Repositorys dieser Organisation eine Branch-Schutzregel, die signierte Commits verlangt. Mitglieder müssen auf ihren Rechnern das Signieren von Commits mit GPG oder SSH einrichten; unsignierte Commits auf den Standard-Branch weist Forgejo beim Push ab.

Die Einstellung greift, sobald du sie speicherst. fremforge wendet sie sofort im Hintergrund auf die bestehenden Repositorys der Organisation an, und die Zeile unter dem Schalter unter Sicherheit › Richtlinien › Repository-Regeln zeigt den Fortschritt und wann er abgeschlossen war. Eine stündliche Prüfung hält danach jeden Standard-Branch auf Linie, auch für später angelegte Repositorys. Speicherst du denselben Wert erneut, startet eine neue Prüfung.

Schaltest du sie aus, wird die Anforderung ebenso sofort wieder abgeschaltet, und zwar in den Regeln, die fremforge für diese Einstellung eingeschaltet hat. Eine Regel, in der ein Repository-Administrator selbst signierte Commits verlangt hat, bleibt unverändert, ebenso der Rest jeder Regel: Freigaben und Statusprüfungen werden nicht angefasst, und keine Regel wird gelöscht. Hat ein Administrator „require signed commits“ in einer Regel, die fremforge bereits gesetzt hatte, von Hand erneut angehakt, kann fremforge die beiden nicht unterscheiden; diese Regel wird mit den anderen abgeschaltet, und der Administrator kann sie erneut setzen.

Es ist eine gemeinsame Einstellung mit der Voreinstellung für signierte Commits in neuen Repositorys: Beim Speichern werden beide gesetzt, sodass ein neues Repository mit derselben Anforderung startet (siehe Repository-Regeln).

Der Schalter ist die Untergrenze auf Organisationsebene; Branch-Schutzregeln einzelner Repos gelten zusätzlich, wenn sie gesetzt sind.

Über die API macht PATCH /orgs/{org}/auth-policy mit require_signed_commits dasselbe und antwortet mit signed_commits_applying: true.

Einrichtung des Signierens für Mitglieder:

# Generate a signing key (or use the existing SSH key)
ssh-keygen -t ed25519 -f ~/.ssh/git-signing-key -C "alice signing key"

# Configure git to sign with it
git config --global user.signingkey ~/.ssh/git-signing-key.pub
git config --global gpg.format ssh
git config --global commit.gpgsign true

# Upload the public key to frem.sh/user/settings/keys with usage:
# "Signing key" alongside the same key as an "Authentication key".

Aktionen im Audit-Log: tenant.auth_policy.signed_commits.enabled / tenant.auth_policy.signed_commits.disabled (die Einstellung); tenant.auth_policy.signed_commits.applied / tenant.auth_policy.signed_commits.reverted (pro Repository-Regel, die fremforge geändert hat).

SSH-Protokoll erlauben

Dieser Schalter legt fest, ob Git über SSH überhaupt erlaubt ist. Aus (Standard für Organisationen, die nach dem 2026-05-22 angelegt wurden) heißt, dass jede Git-Operation über SSH auf den Repositorys der Organisation abgewiesen wird: Push, Clone und Fetch sowie Git LFS über SSH. Clone und Fetch werden abgewiesen, bevor Git startet; ein Push wird im Pre-Receive-Hook abgewiesen. Ein abgewiesener Clone oder Fetch zeigt eine Meldung, die diese Einstellung nennt und die HTTPS-Clone-URL angibt, die stattdessen zu verwenden ist (siehe Was ein abgewiesener Entwickler sieht). Mitglieder nutzen HTTPS + Git Credential Manager, das bei jeder Token-Erneuerung MFA über den IdP deiner Organisation durchreicht. Schalte den Schalter ein, um SSH zu erlauben (der alte Standard vor dem 2026-05-22).

Warum es das gibt: Die IP-Allowlist deckt Git über SSH nicht ab. SSH erreicht fremforge über einen Load Balancer, der die Absenderadresse durch die eines unserer eigenen Cluster-Knoten ersetzt. Die Adresse, von der aus sich dein Entwickler verbindet, ist für uns also nicht sichtbar, und fremforge weigert sich, eine Verbindung nach einer Adresse zu beurteilen, von der es weiß, dass sie falsch ist. Organisationen, die jede Git-Operation nach IP filtern wollen, schalten SSH hier ab und nutzen HTTPS, das die Allowlist abdeckt.

Was ein abgewiesener Entwickler sieht

Ein git clone oder git fetch über SSH auf ein Repository einer Organisation mit abgeschaltetem SSH schlägt so fehl:

$ git clone git@frem.sh:acme/web.git
Cloning into 'web'...
Forgejo: SSH is turned off for the organisation acme (Authentication policy: "Allow SSH protocol" is off), so SSH push, clone and fetch are refused. Use HTTPS instead: git clone https://frem.sh/acme/web.git

fatal: Could not read from remote repository.

Die SSH-Schlüssel des Entwicklers und seine Mitgliedschaft in der Organisation bleiben unberührt: Schaltest du den Schalter wieder ein, ist der SSH-Zugriff sofort wiederhergestellt.

Jede Abweisung wird im Audit-Log als git.ssh.tenant_disabled_blocked festgehalten, für Pushes ebenso wie für Clone und Fetch.

Aktionen im Audit-Log: tenant.auth_policy.ssh_disabled.enabled / tenant.auth_policy.ssh_disabled.disabled.

IP-Allowlist

Die IP-Allowlist hat jetzt eine eigene Seite: IP-Allowlist. Eine einzige Liste deckt nun jeden HTTPS-Bereich ab, es gibt also keinen Geltungsbereich mehr auszuwählen. Die reine Audit-Vorschau, der Runner-Schalter und der Break-Glass-Zugang sind dort beschrieben.

Aufbewahrung des Audit-Logs

Steuert das abfragbare Fenster für Inhalte des Audit-Logs. Die kryptografische Kettenstufe (3 Jahre WORM) ist von dieser Einstellung nicht betroffen; nur die lesbaren Spalten actor und fields_json ändern sich.

Die Einstellung greift beim täglichen Schwärzungslauf (~02:30 UTC). Ein längeres Fenster hält neu erzeugte Zeilen länger abfragbar; ein kürzeres schwärzt beim nächsten Lauf unwiderruflich alle Zeilen, die älter als das neue Fenster sind. Die vollständige Funktionsweise steht unter Audit-Log → Aufbewahrung.

Aktion im Audit-Log: tenant.auth_policy.audit_retention.updated.

Wie sie zusammenspielen

Was was durchsetzt

Diese Richtlinien werden auf Plattformebene bei jeder Anfrage durchgesetzt. Die Verwaltungsoberfläche ist die maßgebliche Quelle dafür, was die Organisation gewählt hat.

Grenzen

• Die Grenze für die PAT-Laufzeit gilt bei der Ausstellung. Bestehende Token werden NICHT rückwirkend verkürzt. Verschärfst du die Grenze, rechne damit, dass einige Bot- oder CI-Token die neue Richtlinie überdauern; sie funktionieren bis zu ihrem ursprünglichen Ablauf weiter.
• Die Pflicht zu Hardware-Schlüsseln gilt nur für NEU hinzugefügte Schlüssel. Mitglieder behalten ihre bestehenden Schlüssel.
• Signierte Commits werden beim Speichern der Einstellung im Hintergrund auf bestehende Repos angewendet; in einer großen Organisation dauert das ein bis zwei Minuten, und der Fortschritt erscheint unter dem Schalter. Neue Repos, die nach dem Einschalten angelegt werden, erhalten die Regel bei der Anlage.