Document the local login page, single logout, and forced redirect - #120
Merged
Merged
Conversation
FOG 1.6 can now be told to send everyone straight to an identity provider, and to end the provider's session when FOG's ends. Both are per-provider settings on the OIDC plugin, both ship off, and one of them can lock every administrator out of a server. ## A page of its own for management/login.php The forced-redirect setting is only safe because there is one URL that always renders FOG's own login form and can never be redirected. That is not a footnote in a plugin page: somebody reaching for it is locked out, in a hurry, and cannot go looking. It needs to be findable by searching for what they are experiencing, which is why the page carries aliases for "break-glass login", "emergency login", "bypass SSO login" and the plain filename. What it covers, in the order somebody would need it: the URL first, then why it exists, then -- because the name invites the wrong reading -- what it does NOT relax. It is the same login: same password check, same roles, same audit trail. The only difference is where the page will and will not send you. Two things there that are easy to get wrong and expensive to discover late: - An account FOG PROVISIONED cannot use it. Those are created with a random token nobody has ever seen, so there is no password to type. Only accounts an administrator created keep a local password. That distinction is the whole of a break-glass plan, so the page says to check it rather than assume it. - The floor FOG enforces preserves, it does not require. An install that has deliberately moved every administrator to a directory has nothing left for it to protect, and this page will not help them. Better said out loud than discovered during an outage. ## The two OIDC settings Both in oidc.md, next to the behaviour they change: - Signing out, including the post-logout redirect URI that has to be registered at the provider and where to put it in Keycloak, Entra and Okta. Providers refuse an unregistered one and show their own error page, which looks exactly like FOG being broken. - Sending everyone straight to the provider, opening with the warning rather than closing with it, and naming the escape hatch inside the warning. Also: why two flagged providers refuse to redirect at all rather than silently picking one. The interaction between them gets its own section, because it is the question an admin will actually have: with single logout ON, logging out returns you to the ordinary login page, which redirects, and the provider -- having genuinely lost its session -- asks who you are. With it OFF, that journey would sign you straight back in, so FOG lands you on the local login page instead. Six new troubleshooting rows for the symptoms these produce, all of which present as "the login page is broken" rather than as a setting. Written against plugin v1.6.10; the post-logout URI callout names the v1.6.9 value it replaces, because an install that enabled single logout at that version has a stale registration at its provider.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Covers three things that landed in FOG 1.6 this week:
fogproject#1175
(
management/login.php), and the two per-provider OIDC settings it existsalongside — fog-plugins#18
(single logout) and
#19 (forced redirect),
as corrected by #20.
New page:
management/web/local-login.mdThe forced-redirect setting is only safe because one URL always renders FOG's
own login form and can never be redirected. That is not a footnote in a plugin
page — somebody reaching for it is locked out, in a hurry, and cannot go
looking. Hence aliases for break-glass login, emergency login, bypass SSO
login and the bare filename, so it is findable by the symptom rather than by
the name we gave it.
Ordered the way somebody needs it: the URL first, then why it exists, then —
because the name invites the wrong reading — what it does not relax. It is
the same login: same password check, same roles, same audit trail. The only
difference is where the page will and will not send you.
Two points that are easy to get wrong and expensive to discover late:
token nobody has ever seen, so there is no password to type. Only accounts an
administrator created keep a local password — and that distinction is the
break-glass plan, so the page says to check it rather than assume it.
deliberately moved every administrator to a directory has nothing left for it
to protect, and this page will not help them. Better said out loud than
discovered during an outage.
oidc.mdTwo new sections next to the behaviour they change, plus the field table and six
troubleshooting rows — all of which present as "the login page is broken" rather
than as a setting.
Signing out covers the post-logout redirect URI that must be registered at
the provider, and where it lives in Keycloak, Entra ID and Okta. Providers refuse
an unregistered one and show their own error page, which looks exactly like FOG
being broken. It carries a callout naming the v1.6.9 → v1.6.10 change in that
value, because an install that enabled single logout at v1.6.9 has a stale
registration right now.
Sending everyone straight to the provider opens with the warning rather than
closing with it, and names the escape hatch inside the warning. Also covers why
two flagged providers refuse to redirect at all rather than silently picking one.
Their interaction gets its own section, because it is the question an admin will
actually have: with single logout on, logging out returns you to the ordinary
login page, which redirects, and the provider — having genuinely lost its session
— asks who you are. With it off, that journey would sign you straight back
in, so FOG lands you on the local login page instead.
Verification
npm run docs:build→ 107 files, 927 emitted, no errors. Checked specifically:no
[[survives into the built HTML (the silent wikilink-across-a-newlinefailure), every heading anchor referenced exists, every wikilink target file
exists, and no duplicate
context_idsite-wide.