Naar de hoofdinhoud

Noodtoegang bij SSO

Wordt SSO voor je organisatie afgedwongen, dan loggen leden in via je identiteitsprovider. Wordt die IdP onbereikbaar of verkeerd ingesteld, of gaat de SSO-koppeling stuk, dan werkt de normale inlogpagina van de organisatie niet meer en kunnen leden zich niet aanmelden. Deze pagina beschrijft hoe je de toegang herstelt zonder te wachten tot de IdP terug is.

Wat stuk gaat en wat niet

De SSO-inlog van de organisatie op frem.sh/user/login?redirect_to=/<org> dwingt SSO af. Is de IdP onbereikbaar of verkeerd ingesteld, dan mislukt de redirect en zien leden een foutmelding.

De lokale fremforge-inlog op https://frem.sh/user/login staat daar los van. Die accepteert een lokale gebruikersnaam en wachtwoord en loopt niet via de SSO-configuratie van de organisatie. Eigenaren van een organisatie hebben altijd lokale inloggegevens en kunnen deze route gebruiken, ook als SSO plat ligt.

Stap 1: log als eigenaar in via de lokale inlog

Ga rechtstreeks naar:

https://frem.sh/user/login

Gebruik niet frem.sh/user/login?redirect_to=/<org>. Die pagina dwingt SSO af en mislukt.

Vul je lokale fremforge-gebruikersnaam en -wachtwoord in. Staat tweefactorauthenticatie aan op je lokale account, rond dan ook die stap af. Zie Tweefactorauthenticatie als je TOTP niet beschikbaar is.

Stap 2: zet de afdwinging van SSO uit

Zodra je als eigenaar bent ingelogd:

  1. Ga naar Organisatiebeheer → SSO → Auth-bronnen (frem.sh/<org>/_admin/sso).
  2. Zoek de auth-bron die niet werkt.
  3. Klik op Verwijderen en bevestig op de pagina /_admin/sso/auth-sources/<id>/delete-confirm. (Er is vandaag geen schakelaar om uit te zetten: door de auth-bron te verwijderen, werkt inloggen met een wachtwoord weer. Zodra de IdP is hersteld, maak je de bron opnieuw aan via de SSO-wizard.)

Door de auth-bron uit te schakelen, kunnen alle leden van de organisatie weer met een wachtwoord inloggen terwijl jij het probleem met de IdP onderzoekt en oplost. Leden kunnen nu inloggen op frem.sh/user/login?redirect_to=/<org> met hun lokale fremforge-inloggegevens.

Stap 3: herstel de IdP

Met de afdwinging van SSO uit heb je tijd om te debuggen zonder dat gebruikers buitengesloten zijn. Veelvoorkomende oorzaken:

  • Certificaat verlopen: het ondertekeningscertificaat van de IdP is verlopen. Exporteer het certificaat opnieuw en werk het bij in de configuratie van de auth-bron. Zie OIDC-SSO.
  • Redirect-URI komt niet overeen: de callback-URL die bij de IdP is geregistreerd, komt niet overeen met wat fremforge stuurt. Vergelijk https://frem.sh/user/oauth2/<auth-source-name>/callback, met de exacte Name die op de kaart van de auth-bron in Organisatiebeheer → SSO staat, met wat in de IdP-app is geregistreerd.
  • Storing bij de IdP: ligt de IdP zelf plat, wacht dan tot die herstelt. In dat geval hoef je niets aan fremforge te veranderen.

Stap 4: zet SSO weer aan

Zodra de IdP werkt:

  1. Ga naar Organisatiebeheer → SSO en doorloop de SSO-wizard op /<org>/_admin/sso/wizard/start om de auth-bron met de gecorrigeerde configuratie opnieuw aan te maken.
  2. Test de SSO-inlog in een privévenster op frem.sh/user/login?redirect_to=/<org> en controleer dat die lukt.
  3. Zodra de nieuwe auth-bron actief is, wordt SSO weer afgedwongen voor de organisatie.

Als de lokale inloggegevens van de eigenaar onbekend zijn

Is het account van de eigenaar uitsluitend via SSO aangemaakt en is er nooit een lokaal wachtwoord ingesteld, dan werkt de bovenstaande noodroute niet.

Neem contact op met support@frem.sh met de onderwerpregel “SSO break-glass”. Vermeld:

  • De slug van je organisatie
  • Het geregistreerde e-mailadres van de eigenaar
  • Een beschrijving van de situatie

Support verifieert je identiteit via een ander kanaal en geeft een tijdelijk token uit waarmee het lokale wachtwoord van het eigenaarsaccount opnieuw kan worden ingesteld. Je krijgt binnen één werkdag antwoord, volgens de SLA van support. Zie Support voor de openingstijden.

Het noodaccount is blijvend: houd het en beveilig het

Het eerste beheerdersaccount dat fremforge aanmaakt wanneer je een organisatie registreert, is je noodaccount. Verwijder het niet nadat je SSO hebt gekoppeld. Zonder een lokale eigenaar die los van de IdP kan inloggen op frem.sh/user/login, sluit een storing of verkeerde instelling bij de IdP de hele organisatie buiten en is voor herstel een supportticket nodig (zie Als de lokale inloggegevens van de eigenaar onbekend zijn hierboven).

Beveilig het lokale account daarom zo dat je het veilig kunt bewaren, ook als SSO de dagelijkse route is:

  1. Vervang het startwachtwoord door een lang, willekeurig wachtwoord bij de eerste inlog (User settings → Security → Password). Het wachtwoord uit de welkomstmail is eenmalig en moet je meteen vervangen. Laat een wachtwoordmanager een wachtwoord van 24 tekens of meer genereren; je hoeft het zelden in te typen.
  2. Zet tweefactorauthenticatie aan op het lokale account. fremforge/Forgejo ondersteunt TOTP (elke authenticator-app) en WebAuthn/passkeys (User settings → Security → Two-factor authentication). Tweefactorauthenticatie op het noodaccount is verplicht, niet optioneel: een lang willekeurig wachtwoord zonder tweede factor is nog steeds één factor die te phishen is, en een noodroute met één factor ondermijnt het hele punt van verplichte SSO. Bewaar de herstelcodes op een veilige plek (een versleutelde wachtwoordmanager, een verzegelde envelop in een kluis, niet in een Slack-DM).
  3. Controleer dat de lokale inlog nog werkt voordat je SSO op afdwingen zet. Open een privévenster, ga naar https://frem.sh/user/login, log in met het lokale wachtwoord plus tweede factor en controleer dat je bij Org admin → SSO komt. Doe dit terwijl je normale sessie nog open is in een gewoon venster, zodat je kunt herstellen als er iets misgaat.
  4. Houd minstens twee eigenaren, die elk de bovenstaande stappen zelfstandig hebben doorlopen. Verliest een eigenaar de toegang (apparaat kwijt, laptop gestolen, nieuwe baan), dan kan de tweede eigenaar de toegang herstellen zonder via support te gaan. Voor organisaties met afgedwongen SSO is dit de maatregel met verreweg het meeste effect.
  5. Plan elk kwartaal een nood-oefening. Eens per kwartaal logt een eigenaar in via de lokale route, controleert dat tweefactorauthenticatie werkt en verifieert dat het uitzetten van SSO nog werkt. Kost weinig en vangt het “ik ben mijn herstelcodes kwijt”-probleem op een moment dat er weinig op het spel staat.

Kruisverwijzingen