Skip to main content
Private preview. fremforge is in private preview — invited customers only. Content is still subject to change. Request access →
Org admin
SSO break-glass

SSO break-glass

When SSO is enforced for your org, members sign in via your identity provider. If that IdP becomes unavailable, misconfigured, or the SSO connection breaks, the normal org login page stops working and members cannot authenticate. This page covers how to restore access without waiting for the IdP to come back.

What breaks and what doesn’t

The org-specific SSO login at frem.sh/user/login?redirect_to=/<org> enforces SSO. When the IdP is unreachable or misconfigured, the redirect fails and members see an error.

The local fremforge login at https://frem.sh/user/login is separate. It accepts local username and password credentials and does not go through the org’s SSO configuration. Org owners always have local credentials and can use this path even when SSO is down.

Step 1: sign in as org owner via local login

Navigate directly to:

https://frem.sh/user/login

Do not use frem.sh/user/login?redirect_to=/<org>. That page enforces SSO and will fail.

Enter your local fremforge username and password. If 2FA is enabled on your local account, complete the 2FA step as well. See Two-factor authentication if your TOTP is unavailable.

Step 2: disable SSO enforcement

Once signed in as an org owner:

  1. Go to Org admin → SSO → Auth sources (frem.sh/<org>/_admin/sso).
  2. Find the auth source that is failing.
  3. Click Disable.

Disabling the auth source restores password-based login for all org members while you investigate and fix the IdP issue. Members can now sign in at frem.sh/user/login?redirect_to=/<org> with their local fremforge credentials.

Step 3: fix the IdP

With SSO enforcement off, you have time to debug without users being locked out. Common causes:

  • Certificate expired: the IdP’s signing certificate expired. Re-export the cert and update it in the auth source configuration. See SAML 2.0 or OIDC SSO.
  • Redirect URI mismatch: the callback URL registered in the IdP doesn’t match what fremforge sends. Compare the exact redirect URI in Org admin → SSO → auth source → Details against what’s registered in the IdP app.
  • IdP outage: if the IdP itself is down, wait for it to recover. No changes to fremforge are needed in this case.
  • SAML clock skew: more than 5 minutes of clock difference between the IdP server and fremforge. Resync NTP on the IdP. See Troubleshooting.

Step 4: re-enable SSO

Once the IdP is working:

  1. Test the SSO login in a private browser window at frem.sh/user/login?redirect_to=/<org> to confirm it succeeds before re-enforcing.
  2. Go to Org admin → SSO → Auth sources.
  3. Click Enable on the auth source.
  4. SSO enforcement resumes for the org.

If the org owner’s local credentials are unknown

If the org owner account was created exclusively via SSO and never had a local password set, the break-glass path above won’t work.

Contact support@frem.sh with the subject line “SSO break-glass”. Include:

  • Your org slug
  • The org owner’s registered email address
  • A description of the situation

Support verifies identity out-of-band and issues a temporary local password reset token for the org owner account. Response is within one business day per the support SLA. See Support for business hours.

The break-glass account is permanent, keep it, harden it

The bootstrap admin account fremforge mints when you sign up an org is your break-glass account. Do not delete it after wiring SSO. Without a local owner who can sign in at frem.sh/user/login independently of the IdP, an IdP outage or misconfiguration locks the entire org out and recovery requires a support ticket (see If the org owner’s local credentials are unknown above).

Instead, harden the local account so it’s safe to keep around even when SSO is the day-to-day path:

  1. Rotate the bootstrap password to a long random one on first login (User settings → Security → Password). The welcome-email password is one-time and should be replaced immediately. Generate a 24+ character password from a password manager, you’ll rarely type it.
  2. Enable 2FA on the local account. fremforge / Forgejo supports TOTP (any authenticator app) and WebAuthn / passkeys (User settings → Security → Two-factor authentication). 2FA on the break-glass account is required, not optional, a long random password without 2FA is still a phishable single factor; the break-glass path being a single-factor login defeats the point of mandating SSO. Store recovery codes somewhere safe (encrypted password manager, sealed envelope in a safe, not a Slack DM).
  3. Verify the local login still works before setting SSO to enforced. Open a private browser window, navigate to https://frem.sh/user/login, sign in with the local password + 2FA, confirm you can reach Org admin → SSO. Do this while your normal session is still open in a regular window so you can recover if anything is wrong.
  4. Keep at least two org owners, each with the steps above completed independently. If one owner loses access (lost device, stolen laptop, employment change), the second owner can re-issue access without going through support. This is the single highest-leverage control for SSO-enforced orgs.
  5. Schedule a quarterly break-glass drill. Once a quarter, an owner signs in via the local path, confirms 2FA works, and verifies the SSO disable toggle still works. Cheap, catches the “I forgot my recovery codes” failure mode at low stakes.

Cross-references