Sichere Anmeldung

Der empfohlene Weg zur Git-Anmeldung für Entwicklerinnen und Entwickler ist HTTPS + Git Credential Manager (GCM) – eine interaktive Anmeldung über den IdP deiner Organisation mit MFA bei jeder Token-Erneuerung. In neuen fremforge-Organisationen ist SSH standardmäßig deaktiviert; erfahrene Entwicklerinnen und Entwickler, die gezielt SSH brauchen, können den Admin ihrer Organisation bitten, es wieder zu aktivieren. Diese Seite beschreibt die Einrichtung von GCM für macOS, Linux und Windows sowie einen Abschnitt zu den Ausweichwegen SSH und PATs.

Warum HTTPS + GCM der Standard ist

Eigenschaft	HTTPS + GCM	SSH	PAT
MFA beim Push	✅ über den IdP deiner Organisation, bei jeder Token-Erneuerung	❌ Schlüssel umgeht MFA	❌ statisches Bearer-Token
Quell-IP durch Organisations-Admin durchsetzbar	✅ Vollständig	⚠️ Architekturbedingt nicht möglich (eingebautes SSH von Forgejo + SNAT des Load Balancers)	✅ Vollständig
Lebensdauer der Zugangsdaten	Kurzlebige OAuth-Token, automatische Erneuerung	Langlebiger Schlüssel (bis zur Rotation)	Konfigurierbar, oft Monate
Einrichtungsschritte für Entwickler	Einmalige GCM-Installation + zwei `git config`-Zeilen	Schlüssel erzeugen + bei fremforge hochladen + Agent konfigurieren	Token in der Oberfläche erstellen + in den Git-Credential-Store einfügen
Schadensradius bei verlorenem Laptop	Angreifer braucht dein IdP-Passwort + MFA – kleines Zeitfenster	Die Schlüsseldatei allein genügt – großes Zeitfenster	Das Token allein genügt – bis zur Rotation

GCM ist der Open-Source-Credential-Helper von Microsoft; fremforge bindet ihn über den eingebauten OAuth2-Anbieter von Forgejo an. Er funktioniert auf Entwicklerrechnern mit Windows, macOS und Linux.

HTTPS + Git Credential Manager (empfohlen)

Schritt 1: GCM installieren

# macOS via Homebrew
brew install --cask git-credential-manager

# Linux (Debian/Ubuntu, Fedora, etc. — see GCM repo for distro-specific paths)
curl -sL https://aka.ms/gcm/linux-install-source.sh | sh
git-credential-manager configure

# Windows — bundled with Git for Windows 2.28+ (re-installer prompt offers GCM)

Schritt 2: GCM für fremforge konfigurieren

Führe das einmal pro Arbeitsrechner aus:

# Tell GCM to use the Forgejo/Gitea OAuth provider for frem.sh URLs.
git config --global credential.https://frem.sh.gitProvider gitea

# Use fremforge's pre-registered Git Credential Manager OAuth application.
# Same client_id across every fremforge org — your sign-in still goes
# through your org's own IdP (the per-tenant OIDC source registered at
# /<your-org>/_admin/sso).
git config --global credential.https://frem.sh.oauthClientId e90ee53c-94e2-48ac-9358-a874fb9e0662

Die OAuth-Anwendung ist der eingebaute Client git-credential-manager, den Forgejo mitbringt – eine Registrierung pro Instanz ist nicht nötig; dieselbe Client-ID funktioniert mit jeder fremforge-Instanz und jedem Forgejo-basierten Git-Host. Der Client verwendet PKCE (Proof Key for Code Exchange), daher ist auf dem Rechner der Entwicklerin oder des Entwicklers kein client_secret nötig. Die Loopback-Callbacks (http://127.0.0.1, http://localhost) werden gemäß RFC 8252 §7.3 auf jedem Port akzeptiert.

Schritt 3: Über HTTPS klonen

git clone https://frem.sh/<your-org>/<your-repo>.git

GCM öffnet einen Browser-Tab → frem.sh fragt nach deiner E-Mail-Adresse (damit wir wissen, zu welcher Organisation du gehörst) → leitet dich zur mandantenspezifischen Anmeldeseite deiner Organisation weiter → dort wird nur der IdP-Button (bzw. die Buttons) deiner Organisation angezeigt → du gibst Passwort + MFA bei deinem IdP ein → der Browser kehrt zu GCM zurück → das Token wird zwischengespeichert. Die IdPs anderer Mandanten sind nie sichtbar. Weitere Clones, Fetches und Pushes innerhalb der Lebensdauer des Tokens laufen ohne Rückfrage.

Zugriffstoken gelten 24 Stunden – in diesem Zeitraum läuft jeder Git-Push ohne Rückfrage. Refresh-Token gelten 30 Tage, sodass der nächste Push nach Ablauf des Zugriffstokens es ohne Browser-Abfrage erneuert. Jeder Rechner, an dem du dich anmeldest, behält seine eigene gültige Anmeldung; nutzt du Git auf einem Laptop und einem Desktop (oder in WSL), muss sich keiner der beiden deshalb erneut anmelden. Nach 30 Tagen ohne Push oder Fetch öffnet der nächste Vorgang wieder den Browser, und dein IdP fordert MFA an.

Wenn GCM den Browser öffnet, um dich neu anzumelden (ein neues Gerät, nach einer Abmeldung oder nach 30 Tagen ohne Nutzung), bittet frem.sh dich zuerst, mit deiner Authenticator-App oder deinem Sicherheitsschlüssel zu bestätigen, dass du es bist. Das passiert etwa einmal im Monat auf jedem Gerät; das Erneuern der Anmeldung im Hintergrund fragt nie nach. Siehe Warum werde ich gebeten zu bestätigen, dass ich es bin?

Schritt 4: Optional – sinnvolle Voreinstellungen setzen

# Cache the OAuth token between sessions instead of re-running the
# browser flow every laptop reboot. GCM stores it in the OS keychain
# (macOS Keychain / Windows Credential Manager / Linux libsecret).
git config --global credential.credentialStore gpg     # Linux only
git config --global credential.guiPrompt true          # macOS / Linux

Ausweichwege

Persönliches Zugriffstoken (nur für CI-Bots und Skripte)

PATs sind statische Bearer-Zugangsdaten ohne MFA. Für unbeaufsichtigte Automatisierung sind sie in Ordnung, für Pushes durch Menschen nie.

# 1. Mint at frem.sh/user/settings/applications
# 2. Set expiry to the shortest practical value (30 days for routine,
#    90 days for stable CI). If your org admin has set a max lifetime
#    policy, the mint page caps the dropdown automatically.
# 3. Use as the password for HTTPS clone:
git clone https://<your-username>:<pat>@frem.sh/<org>/<repo>.git

# Or via GCM's "store in keychain" path so you don't bake it into URLs:
git -c credential.helper=store clone https://frem.sh/<org>/<repo>.git
# Enter username + paste PAT when prompted; cached in ~/.git-credentials.

OIDC-Token von Forgejo Actions (Workload-Identität für CI, keine statischen Zugangsdaten)

Für CI/CD, das nach AWS, Azure, GCP oder T Cloud Public deployt, ist föderierte Identität besser als PATs. fremforge gibt CI-Jobs kurzlebige OIDC-Token von seinem Runner-OIDC-Issuer, https://frem.sh/_app/runner/oidc (Discovery unter https://frem.sh/_app/runner/oidc/.well-known/openid-configuration); richte das IAM deines Cloud-Anbieters so ein, dass es diesem Issuer vertraut. Die Claims (sub, aud, repository_owner) stehen auf der unten verlinkten Seite. Vorlagen für die Vertrauensrichtlinien je Cloud findest du unter Runner-OIDC.

SSH (nur, wenn der Admin deiner Organisation es ausdrücklich aktiviert hat)

In neuen fremforge-Organisationen ist SSH standardmäßig deaktiviert. Braucht deine Organisation SSH (ältere CI, ausgeprägte Vorliebe von Entwicklern für den Ablauf mit SSH-Schlüsseln):

Der Organisations-Admin öffnet <your-org>/_admin/auth-policy und setzt das Häkchen bei „SSH-Protokoll erlauben“ – und nimmt damit die dokumentierte Einschränkung in Kauf, dass die IP-Allowlist nicht für SSH gilt.
Mitglieder fügen SSH-Schlüssel unter frem.sh/user/settings/keys hinzu und konfigurieren ihre ~/.ssh/config:

Host frem.sh
    Hostname ssh.frem.sh
    Port 443
    IdentityFile ~/.ssh/id_ed25519

Verwende nach Möglichkeit hardwaregestützte Schlüssel (ssh-add --apple-use-keychain unter macOS für Touch ID; ssh-keygen -t ed25519-sk für FIDO/YubiKey unter Linux). Siehe den Abschnitt zu hardwaregestütztem SSH unten.

Eigene OAuth-Anwendungen: Scopes ausdrücklich anfordern

Registrierst du auf frem.sh eine OAuth2-Anwendung (Einstellungen des Benutzers oder der Organisation › Anwendungen), um Personen anzumelden oder in ihrem Namen die API aufzurufen, kann ihr Token nur das, was die angeforderten Scopes erlauben:

API-Scopes (read:repository, write:issue, read:user und die übrigen): Das Token funktioniert innerhalb dieser Scopes wie bisher mit der API und mit Git über HTTPS.
Nur openid, profile, email, groups: Das Token meldet die Person an und kann sonst nichts. Es funktioniert mit /login/oauth/userinfo und /login/oauth/introspect und erhält 401 bei der API, den Paket-Registrys und Git.
Gar kein Scope: dasselbe, nur Anmeldung. Nur die eigenen Clients von fremforge (Git Credential Manager in der oben beschriebenen Konfiguration und die fremforge-CLI) behalten ohne Scope vollen Zugriff.

Eine Anwendung, die die API braucht, muss also die benötigten API-Scopes im Parameter scope von /login/oauth/authorize anfordern. Hat sie bereits eine Berechtigung mit einem anderen Scope, widerruft die Person diese unter Autorisierte OAuth2-Anwendungen auf frem.sh/user/settings/applications und meldet sich erneut an.

Hardwaregestützte SSH-Schlüssel (für Organisationen, die SSH wieder aktiviert haben)

Hat der Admin deiner Organisation SSH wieder aktiviert und musst du es wirklich nutzen, sind hardwaregestützte Schlüssel verbindliche Best Practice. Die Organisationsrichtlinie „Hardwaregestützte SSH-Schlüssel beim Hinzufügen neuer Schlüssel verlangen“ lehnt bei der Registrierung jeden Schlüssel ab, der nicht zur Algorithmusfamilie sk-* gehört.

macOS – Secure Enclave

ssh-keygen -t ed25519 -C "your-name@your-org" -f ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Touch ID fragt bei jedem Push nach, sofern der macOS-Schlüsselbund den Schlüssel nicht kürzlich entsperrt hat. Soll der Schlüssel vollständig in der Secure Enclave liegen (im Chip erzeugt und ausschließlich dort gehalten), verwende Secretive.

Linux – YubiKey / FIDO-Authenticator

ssh-keygen -t ed25519-sk -C "your-name@your-org" -f ~/.ssh/id_ed25519_sk
ssh-add ~/.ssh/id_ed25519_sk

Für ed25519-sk ist OpenSSH 8.2+ (Februar 2020) erforderlich; auf älteren Distributionen ist ecdsa-sk die Alternative.

Windows – TPM-gestützt über WSL2 / KeePassXC

Das native OpenSSH unter Windows gibt das TPM nicht direkt frei. Zwei Wege:

WSL2 – folge dem Linux-Ablauf innerhalb von WSL2.
SSH-Agent von KeePassXC / 1Password – beide halten Schlüssel, die durch die Biometrie von Windows Hello geschützt sind.

Entscheidungsbaum

Are you a human developer pushing code daily?
├── Yes → HTTPS + GCM (the recommended default; no SSH key needed)
│         ├── If your org has re-enabled SSH and you prefer it → hardware-backed SSH key
│         └── If you specifically need a static credential → PAT with 30-day expiry
└── No, I'm a CI bot or script
    ├── Cloud-deploying → Forgejo Actions OIDC token (no static cred)
    └── Other → PAT with tight scope + short expiry

Was du NICHT tun solltest

Langlebige PATs in Git-Konfigurationsdateien / .netrc. Statische Bearer-Zugangsdaten ohne Ablauf sind das schlechteste Authentifizierungsmuster. Nutze GCM für Menschen, OIDC-Token für CI und PATs mit kurzer Laufzeit für ältere Bots.
Ein einfaches ssh-keygen -t ed25519 ohne Hardwarebindung oder Vorgabe der Organisation. Der Schlüssel liegt in ~/.ssh/; ein verlorener Laptop bedeutet einen kompromittierten Schlüssel für dessen gesamte Lebensdauer.
MFA mit Mustern wie „SSH-Schlüssel immer vertrauen“ umgehen. Braucht deine Organisation eine Durchsetzung auf dem Niveau einer IP-Allowlist, heißt das HTTPS – die IP-Allowlist von fremforge greift bei HTTPS in Echtzeit und ist bei SSH architekturbedingt nicht möglich.
SSH wieder aktivieren, „weil es schneller ist“. Der Unterschied beim Einrichtungsaufwand ist nach dem ersten Tag vernachlässigbar; der Unterschied bei der Sicherheit ist real.

Referenz für Organisations-Admins

Wenn du als Owner einer Organisation Richtlinien festlegst:

Admin-Anleitung zur Authentifizierungsrichtlinie – Schalter zum Deaktivieren von SSH, Pflicht zu hardwaregestützten SSH-Schlüsseln, SSH-Zertifizierungsstelle (am 26.05.2026 integriert), maximale PAT-Laufzeit, Schalter Repo-Deploy-Keys erlauben, signierte Commits, Geltungsbereich der IP-Allowlist + Vorschau im reinen Audit-Modus