Authenticatiebeleid

De pagina Authenticatiebeleid bundelt de instellingen voor de hele organisatie die bepalen hoe je leden zich bij Git en de REST-API authenticeren. Elke schakelaar staat op zichzelf; de standaardwaarden zijn de ruimste, zodat bestaande leden niet onverwacht worden buitengesloten wanneer je de pagina voor het eerst opent. Scherp ze een voor een aan naarmate je beveiliging volwassener wordt.

Je vindt de pagina onder Beveiliging › Toegang › Authenticatiebeleid (<your-org>/_admin/security/access/authentication; het oudere <your-org>/_admin/auth-policy verwijst daarheen door). De pagina begint ook met de informatie over tweefactorauthenticatie die vroeger op de opgeheven pagina Edge policies stond: tweefactorauthenticatie is altijd verplicht, voor elk lid.

Samenvoeging op 2026-05-26: het losse tabblad SSH-certificaatautoriteit is als onderdeel onder “SSH-protocol toestaan” in deze pagina opgenomen (het heeft alleen zin als SSH aanstaat, dus het verschijnt samen met die schakelaar). Directe links naar /admin/ssh-ca/ verwijzen nu hierheen door. Dezelfde schrijfacties blijven bestaan (CA-sleutels plakken, een certificaat verplicht stellen) zonder dat je de pagina Authenticatiebeleid verlaat.

Beleid

Eisen aan SSH-sleutels

Staat dit aan, dan weigert fremforge nieuwe SSH-sleutels die niet hardwaregebonden zijn. Het algoritme van de OpenSSH-sleutel vertelt ons dat: alleen sk-ssh-ed25519@openssh.com en sk-ecdsa-sha2-nistp256@openssh.com voldoen; gewone ssh-ed25519 en ssh-rsa worden in het formulier Sleutel toevoegen geweigerd.

Hardwaregebonden betekent dat de private sleutel in een beveiligingschip staat (macOS Secure Enclave, TPM, YubiKey, FIDO-authenticator). De sleutel kan niet van de laptop worden gehaald. Bij elke push is Touch ID, een pincode of een tik op de hardware nodig. Dit komt in de praktijk het dichtst bij “MFA bij git push” zonder een volledige SSH-certificaatautoriteit in te richten.

Bestaande sleutels worden NIET met terugwerkende kracht geweigerd: alleen nieuw toegevoegde sleutels worden gecontroleerd. Dit aanzetten in een gezonde organisatie is veilig; leden kunnen met hun bestaande sleutels blijven pushen, maar wie een nieuwe laptop toevoegt, moet een hardwaregebonden sleutel instellen. Combineer het met de SSH-certificaatautoriteit hieronder voor de sterkste eindsituatie (helemaal geen gewone sleutels).

Acties in het auditlog: tenant.auth_policy.hardware_keys.enabled / tenant.auth_policy.hardware_keys.disabled.

SSH-certificaatautoriteit

(Alleen zichtbaar als het SSH-protocol hierboven aanstaat: een SSH-bouwsteen tonen zodra SSH aanstaat, is het logische patroon.)

Authenticatie met SSH-certificaten is de sterkste praktische manier om via SSH aan te melden. Een kortlevend certificaat, uitgegeven door je eigen CA en gekoppeld aan de MFA-flow van je IdP, vervangt de langlevende publieke sleutel op elke laptop van een ontwikkelaar. fremforge ondersteunt dit model standaard: dezelfde bouwsteen die GitHub Enterprise Cloud “SSH certificate authority” noemt.

Voorwaarde: sinds 2026-05-22 staat SSH voor nieuwe organisaties in fremforge standaard uit (de schakelaar hierboven). Houdt je organisatie die standaard aan, dan heb je helemaal geen SSH-CA nodig: de route via HTTPS + Git Credential Manager geeft je MFA bij elke push via je IdP, zonder CA in te richten. Heeft je organisatie SSH uitdrukkelijk weer aangezet (omdat je een specifieke reden hebt, zoals oudere CI-tooling of een sterke voorkeur van ontwikkelaars), dan is dit onderdeel de volgende beveiligingslaag voor die gekozen SSH-route.

Wanneer je SSH-CA gebruikt

Gebruik authenticatie met SSH-certificaten als je organisatie SSH weer heeft aangezet EN een of meer van het volgende geldt:

• Je wilt dat elke Git-push afhangt van een verse MFA-uitdaging van de IdP (geen “laptop kwijt → aanvaller pusht 90 dagen lang tot iemand de SSH-sleutel opmerkt”)
• Je migreert vanaf GitHub Enterprise Cloud en je ontwikkelaars verwachten de SSH-CA-flow van GHEC
• Je CISO heeft specifiek om “MFA bij Git-push” gevraagd EN houdt vast aan SSH als transport; let wel: het nettere antwoord is de standaardroute HTTPS+GCM
• Je hebt al een CA die OpenSSH-certificaten uitgeeft (Smallstep, de SSH-secrets-engine van HashiCorp Vault, een eigen uitgever gekoppeld aan OIDC) en wilt dat fremforge de certificaten vertrouwt die hij ondertekent

Zit je in geen van die situaties, dan zijn hardwaregebonden SSH-sleutels (Touch ID, Secure Enclave, YubiKey; de schakelaar hierboven) een eenvoudigere route met vergelijkbare beveiliging. Zie Veilig aanmelden voor het keuzeoverzicht.

Inrichten

Stap 1: je CA voorbereiden. Opties, van eenvoudig naar minder eenvoudig:

1. Smallstep step ca: open source, goed in de EU te hosten, met OIDC-provisioner-ondersteuning ingebouwd. Koppel het aan je IdP en step ssh login wordt een MFA-flow van één regel.
2. SSH-secrets-engine van HashiCorp Vault: draai je Vault al voor secrets, dan voegt de SSH-secrets-engine het uitgeven van OpenSSH-certificaten met toegangsbeheer op basis van beleid toe.
3. Handmatig ssh-keygen -s: alleen als proof of concept.

Maak het sleutelpaar voor de CA aan als je er nog geen hebt:

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

Dat levert acme-ssh-ca op (privé: geheimhouden en alleen naar je uitgevende infrastructuur distribueren) en acme-ssh-ca.pub (publiek: plak je hierna in fremforge).

Stap 2: de CA registreren. Plak acme-ssh-ca.pub in het tekstvak Openbare CA-sleutels (één per regel) op deze pagina, één CA per regel. Er worden maximaal 8 CA’s geaccepteerd (handig bij het roteren: nieuwe toevoegen, nieuwe private sleutel distribueren, oude uitfaseren). Klik op Save CA keys. Een geautomatiseerde platformjob voert de wijziging door in de SSH-laag van Forgejo. Regel in het auditlog: tenant.ssh_ca.keys.updated.

Stap 3: leden hun principals laten registreren. Elk SSH-certificaat bevat een of meer principals: korte tekenreeksen die aangeven voor wie het is. Een certificaat dat door een vertrouwde CA is ondertekend, meldt een lid aan wanneer een van zijn principals overeenkomt met een principal die dat lid op zijn eigen instellingenpagina voor SSH-sleutels heeft geregistreerd (het onderdeel Beheer SSH-certificaat verantwoordelijke). fremforge accepteert daar elke tekenreeks als principal, dus geef certificaten uit waarvan de principal de gebruiker eenduidig aanwijst, bijvoorbeeld diens fremforge-gebruikersnaam.

Verwijderd op 2026-10-14: de instelling “Principal policy” (Username / Email / Anything). Ze werd opgeslagen maar nooit afgedwongen: Forgejo controleert de vorm van een principal tegen één instelling voor het hele platform, niet per organisatie, en een lid kan tot meerdere organisaties behoren. PUT /orgs/{org}/ssh-ca van de API accepteert principal_policy nog, zodat bestaande scripts en Terraform blijven werken, maar negeert het, en GET geeft het niet meer terug.

Stap 4: certificaatauthenticatie eventueel verplicht stellen. Zodra er minstens één CA is ingesteld, zet je Door de CA ondertekend certificaat vereisen aan om gewone SSH-authenticatie met een publieke sleutel te weigeren. Dat is de schoonste eindsituatie: langlevende ~/.ssh/id_*-sleutels werken helemaal niet meer, en elke Git-push moet via je CA (en dus via de MFA-flow van je IdP). Dit aanzetten zonder werkende CA zou iedereen buitensluiten; het formulier weigert de wijziging als er geen CA is ingesteld. Regels in het auditlog: tenant.ssh_ca.require_cert.enabled / tenant.ssh_ca.require_cert.disabled.

Stap 5: gebruikers hun eerste certificaat geven. Met 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.

Zie voor Vault de documentatie van de SSH-secrets-engine van HashiCorp Vault. Voor handmatig ssh-keygen -s (alleen als POC): ssh-keygen -s acme-ssh-ca -I "alice-cert-2026-05-22" -n alice -V +1h alice-id_ed25519.pub → geef alice-id_ed25519-cert.pub samen met de private sleutel aan de gebruiker; OpenSSH pikt het automatisch op.

De CA roteren

Een bestaande CA vervangen zonder onderbreking: maak een nieuw CA-sleutelpaar aan → voeg de nieuwe publieke sleutel naast de bestaande toe aan het tekstvak (maximaal 8) → laat je CA-infrastructuur met de nieuwe sleutel uitgeven → wacht tot de certificaten van de oude CA verlopen zijn (meestal 1 uur) → verwijder de oude CA uit het tekstvak.

CA-authenticatie uitschakelen

Verwijder alle CA-sleutels uit het tekstvak en sla op. De auditregel tenant.ssh_ca.keys.updated legt next_key_count: 0 vast. Stond Door de CA ondertekend certificaat vereisen aan, dan gaat die automatisch uit (de schakelaar vereist minstens één CA). Leden gaan terug naar gewone SSH-authenticatie met een publieke sleutel.

PAT-levensduur

De maximaal toegestane levensduur van nieuw aangemaakte persoonlijke toegangstokens. Bestaande tokens worden NIET met terugwerkende kracht ingekort; de grens geldt alleen bij het uitgeven.

Aanbevolen: 90 dagen als beginpunt. Scherp aan tot 30 als je een actief programma voor het scannen op credentials hebt dat gelekte tokens binnen de rotatieperiode vindt.

Actie in het auditlog: tenant.auth_policy.max_pat_lifetime.updated.

Deploysleutels op repository’s toestaan

Deploysleutels op een repository zijn langlevende SSH-credentials die tot één repository zijn beperkt: een tweede route voor langlevende machinecredentials naast PAT’s van gebruikers. Handig voor externe CI- of mirrorclients die niet via OIDC kunnen federeren. Standaard: uit, in lijn met de standaard veilige houding van ssh_disabled=true en allow_user_pats=false. Langlevende machinecredentials staan uit tot je er zelf voor kiest.

Staat het beleid uit (standaard), dan grijpen drie lagen in:

1. Banner in de UI van Forgejo: opent een repositorybeheerder Repo-instellingen → Deploy sleutels, dan loopt de pagina via api-intercept, dat boven de standaardheader van Forgejo een banner in Fomantic-stijl invoegt die uitlegt dat deploysleutels door het beleid van de organisatie zijn uitgeschakeld. De navigatie en zijbalk van Forgejo blijven staan (de gebruiker wordt nooit uit de repository gestuurd). Het versturen van het formulier Deploy sleutel toevoegen wordt in de API geblokkeerd (de POST krijgt een 303-doorverwijzing terug naar de GET, zodat de gebruiker de uitleg in de banner ziet).
2. Blokkade in de REST-API: POST /api/v1/repos/<owner>/<repo>/keys geeft 403 terug met error: use_fremforge_admin en een redirect_to die naar deze pagina wijst. DELETE en GET worden altijd doorgestuurd (beheerders kunnen bestaande sleutels ongeacht het beleid opruimen en auditen).
3. Zachte waarschuwing in het auditlog: elke bestaande actieve deploysleutel levert bij de volgende controleronde een auditgebeurtenis tenant.auth_policy.deploy_key_violation op. Bestaande sleutels worden NIET automatisch ingetrokken; de beheerder beslist welke weg moeten via de repository-instellingen van Forgejo (de route om te verwijderen blijft open).

Wanneer aanzetten: alleen voor het nichegeval van externe CI- of mirrorclients die echt niet via OIDC kunnen federeren. Het bedoelde alternatief voor de machine-identiteit van CI is OIDC-federatie voor runners: kortlevende tokens van de OIDC-issuer van fremforge, gefedereerd met het trustbeleid van je cloud, zonder langlevende secret per repository. De meeste CI-integraties hebben geen deploysleutels nodig.

Acties in het auditlog: tenant.auth_policy.allow_repo_deploy_keys.enabled / .disabled (de schakelaar); tenant.auth_policy.deploy_key_violation (per actieve sleutel zolang het beleid uit staat).

Ondertekende commits vereisen

Staat dit aan, dan heeft de standaardbranch van elke repository in deze organisatie een regel voor branchbescherming die ondertekende commits vereist. Leden moeten het ondertekenen van commits met GPG of SSH op hun machines instellen; niet-ondertekende commits naar de standaardbranch worden bij de push door Forgejo geweigerd.

De instelling werkt zodra je haar opslaat. fremforge begint haar direct op de bestaande repository’s van de organisatie toe te passen, op de achtergrond, en de regel onder de schakelaar in Beveiliging › Beleid › Repositoryregels toont de voortgang en wanneer het klaar is. Daarna houdt een controle elk uur elke standaardbranch in lijn, ook voor repository’s die later worden aangemaakt. Sla je dezelfde waarde opnieuw op, dan start een nieuwe controle.

Zet je haar uit, dan wordt de eis ook weer direct uitgeschakeld, op de regels die fremforge voor deze instelling had aangezet. Een regel waarin een repositorybeheerder zelf ondertekende commits verplichtte, blijft zoals hij is, en hetzelfde geldt voor de rest van elke regel: goedkeuringen en statuscontroles worden niet aangeraakt, en er wordt geen regel verwijderd. Heeft een beheerder “require signed commits” met de hand opnieuw aangevinkt op een regel die fremforge al had ingesteld, dan kan fremforge die twee niet uit elkaar houden; die regel wordt met de andere uitgezet, en de beheerder kan hem opnieuw instellen.

Het is één instelling samen met de standaard voor ondertekende commits in nieuwe repository’s: opslaan stelt beide in, zodat een nieuwe repository met dezelfde eis begint (zie Repositoryregels).

De schakelaar is de ondergrens op organisatieniveau; als er regels voor branchbescherming per repository zijn ingesteld, gelden die.

Via de API doet PATCH /orgs/{org}/auth-policy met require_signed_commits hetzelfde en antwoordt met signed_commits_applying: true.

Ondertekenen instellen voor leden:

# 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".

Acties in het auditlog: tenant.auth_policy.signed_commits.enabled / tenant.auth_policy.signed_commits.disabled (de instelling); tenant.auth_policy.signed_commits.applied / tenant.auth_policy.signed_commits.reverted (per repositoryregel die fremforge heeft gewijzigd).

SSH-protocol toestaan

Deze schakelaar bepaalt of Git over SSH überhaupt is toegestaan. Uit (standaard voor organisaties die na 2026-05-22 zijn aangemaakt) betekent dat elke Git-bewerking via SSH op de repository’s van de organisatie wordt geweigerd: push, clone en fetch, en Git LFS over SSH. Clone en fetch worden geweigerd voordat Git start; een push wordt in de pre-receive-hook geweigerd. Een geweigerde clone of fetch toont een melding die deze instelling noemt en de HTTPS-clone-URL geeft die je in plaats daarvan gebruikt (zie Wat een geweigerde ontwikkelaar ziet). Leden gebruiken HTTPS + Git Credential Manager, dat bij elke vernieuwing van het token MFA via de IdP van je organisatie afdwingt. Zet de schakelaar aan om SSH toe te staan (de oude standaard van vóór 2026-05-22).

Waarom dit bestaat: de IP-toegestane lijst dekt Git over SSH niet. SSH bereikt fremforge via een load balancer die het bronadres vervangt door dat van een van onze eigen clusternodes, zodat we het adres waarvandaan je ontwikkelaar verbindt niet zien, en fremforge weigert een verbinding te beoordelen op een adres waarvan het weet dat het niet klopt. Organisaties die elke Git-bewerking op IP willen filteren, zetten SSH hier uit en gebruiken HTTPS, dat de lijst wel dekt.

Wat een geweigerde ontwikkelaar ziet

Een git clone of git fetch via SSH op een repository van een organisatie waar SSH uitstaat, mislukt met:

$ 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.

De SSH-sleutels van de ontwikkelaar en diens lidmaatschap van de organisatie blijven onaangeroerd: zet je de schakelaar weer aan, dan werkt SSH-toegang direct weer.

Elke weigering wordt in het auditlog vastgelegd als git.ssh.tenant_disabled_blocked, voor pushes en voor clone en fetch.

Acties in het auditlog: tenant.auth_policy.ssh_disabled.enabled / tenant.auth_policy.ssh_disabled.disabled.

IP-toegestane lijst

De IP-toegestane lijst heeft nu een eigen pagina: IP-toegestane lijst. Eén lijst dekt nu elk HTTPS-oppervlak, dus er is geen bereik meer om te kiezen. De voorvertoning met alleen audit, de schakelaar voor runners en de noodtoegang staan daar beschreven.

Bewaartermijn auditlog

Bepaalt de periode waarin de payload van het auditlog doorzoekbaar is. De cryptografische ketenlaag (3 jaar WORM) wordt door deze instelling niet geraakt; alleen de leesbare kolommen actor + fields_json veranderen mee.

De instelling wordt toegepast bij de dagelijkse redactieronde (~02:30 UTC). Een langere periode houdt nieuw geschreven rijen langer doorzoekbaar; een kortere periode redigeert bij de volgende ronde onomkeerbaar de rijen die ouder zijn dan de nieuwe periode. Zie Auditlog → Bewaring voor de volledige werking.

Actie in het auditlog: tenant.auth_policy.audit_retention.updated.

Hoe ze samenwerken

Wat wat afdwingt

Deze beleidsregels worden bij elk verzoek in de platformlaag afgedwongen. De beheer-UI is de bron van waarheid voor wat de organisatie heeft gekozen.

Beperkingen

• De grens voor de PAT-levensduur geldt bij het uitgeven. Bestaande tokens worden NIET met terugwerkende kracht ingekort. Scherp je de grens aan, reken er dan op dat sommige bot- of CI-tokens langer leven dan het nieuwe beleid; ze blijven werken tot hun oorspronkelijke vervaldatum.
• Het afdwingen van hardwaresleutels geldt alleen voor NIEUW toegevoegde sleutels. Leden houden hun bestaande sleutels.
• Ondertekende commits worden bij het opslaan van de instelling op de achtergrond op bestaande repository’s toegepast; bij een grote organisatie duurt dat een minuut of twee, en de voortgang staat onder de schakelaar. Nieuwe repository’s die worden aangemaakt terwijl de schakelaar aanstaat, krijgen de regel bij het aanmaken.